inquirex-tools 0.8.0 → 0.9.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2027915b1b69d07af80a30a63207731809243ae607da736ea2d558c2748c6c1f
-  data.tar.gz: 6c35d199ad702ffd061d90bf5fa5ebe17da1fc8b1f0d7722e3f8bf37676b3e4b
+  metadata.gz: d8f0e3e2dc5bcc9d45d3c9cba64f8a7d96400b6d1296d316ff56460ece229166
+  data.tar.gz: 3ee07acd2e8e731115e0a5552bbbdaeea2979198195e396fc946765f8b6deef6
 SHA512:
-  metadata.gz: a97efe3bc05fc24445e9b40920ec073055305e26c92764a7977cea0152cd33a25c28ccca97cf3e129ced24150b5957f0a137c57bc10172c1054cea7a5300ddfb
-  data.tar.gz: 0a975ec1e72ad597bf19827d9fe5f5afe68523bfea5809729a23ae184ab61a380b7aeff9128df1e984042c307a9de6c4ea464c660bf668474e731aa78779664e
+  metadata.gz: 81ca8eed0f60037439fd3c8ab6aafe9b35114082f2c02db488bf279a3d52577c7fb7c8c7e04a41ab48e0c8ab6be1e8e71e324d32b566cbc865ce861e4855601e
+  data.tar.gz: 3adc9867dab085361badf7b00ff38ef9965345efa2ef610bddb27e35e2a34945ebaa2459bdf068e18118cd2121ec67f952564f2f9df562e00d53df49ebb63578

data/.env.encrypted

@@ -0,0 +1,11 @@
+#ENC[AES256_GCM,data:4mpgKeRs3A2HXmt/FjaIn561sybb9L9oX7gVygSpct//wHWjT5I+lT3Vf5UlMGTv42RKAAL5CgF+SRr4bni33A6CeU3ODQ3vYAo=,iv:oP7xJ9m3C0ezlTznZ1NkqCvu52MLHpDnTkmc7Q0lhhY=,tag:7SoYBTYtcIex2jgqECrAuA==,type:comment]
+#ENC[AES256_GCM,data:89N9zu88zeviY33xeiZOFaLTDxv51jf8SmuZ07NVzAOUDdQAPkKuYkqvOOZpYXjYTDJVY16yYLMYGSmVq8f5rbmWDYC/gJn31m0=,iv:01XkrGj3H6uf6tIdHZxSEpJ/a8LVpo/TidFgRHTJUXo=,tag:lTMSW/QgGaWub1pZrre9TA==,type:comment]
+#ENC[AES256_GCM,data:nYuulT9DlDl+zOPlhK0IqJSahj1KiunqenUbfzPllxxEvJNqMUKU/kVaK73YbaDSUPdAeRXbFH3trz8CQ4uBR5yjQCnv12DD9VVjXw==,iv:7hWr2ajKbKA7lPqtBsmvUycJTF69PVcHUk1kA0T6kXo=,tag:2fnWYnft/u2hVkadn5dsdw==,type:comment]
+#ENC[AES256_GCM,data:kDDhc1ZMB8McDQ2dcEnvT24UWRUq/WNKJ/QuhFpO54K6P0IXFUbmBoqIK2X408HPcJLz9etlw7NAZt1AaQ==,iv:+BRUu6mSooyQt+bazHq/dgXVISTjEfiIJTyUR0N9XgI=,tag:pU6kCwETMJ4neWSHLDBX9g==,type:comment]
+OP_ACCOUNT=ENC[AES256_GCM,data:QLsZSJQqdNSFAIqVDBVHh4kO9TrP9Hm4CZA=,iv:qlqTEsjHfV5AowWnsgWYjU2udMgFmXsYF3GK1PIjzsw=,tag:PUivzRC+pPufSY5P+HG9Rg==,type:str]
+sops_age__list_0__map_enc=-----BEGIN AGE ENCRYPTED FILE-----\nYWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IHBpdi1wMjU2IER3YUVVQSBBMHphcXd3\nNmtHWjkxVDdwZDZON213c3hmeEpGbW9GSmszM2ZWUGxxRWoyQwpReTZ3bzZFeEJM\nWlF0VVFTNGVnaFlmMVRSUmtoVEZKOCtVRlU1VjYya25FCi0tLSBJTEtJcTducjM4\nSndWNmZub1hiMCsxMTFwbkpSTXVtZnNKemt6UGpzS1BRCptxoolSJ98Ngajq1/pI\nWo0FMY9hEPh5m1m0lBcWBRqbnr23APyywtt89b0UOKhRHhf9KMw6zTfk+KQC3wj0\nNug=\n-----END AGE ENCRYPTED FILE-----\n
+sops_age__list_0__map_recipient=age1se1qd8tpc9v42uuqz974uxx84mdz0aejujrzssmyjl6fvmwgx3gm62wjjxjyws
+sops_lastmodified=2026-08-06T01:38:07Z
+sops_mac=ENC[AES256_GCM,data:4J6BN+p3cXmbGMOfmjXtkPDvRI1jlflrEObvC30TwwrbBXhBW+WLSUOiGM8aVC+pSCzCNykpjkKw47ElMA8jD927xMg1BaglWTtbFPaqVgCVXXnM0c1XL6+oWa80QULZGXViG4W7c4JTYxzqsvhGEpKx0CUFO43GKibx/BaUgAo=,iv:+F76/yNF/kctS0844U7IS9RUyMIg4fkltqlbS+l9mrQ=,tag:rwtNHQpXnEuDLl77qMesZw==,type:str]
+sops_unencrypted_suffix=_unencrypted
+sops_version=3.13.2

data/.env.example

@@ -0,0 +1,5 @@
+# Example environment variables for this project.
+# Copy this file to `.env`, fill in real values, then encrypt with sopsy.
+# `.env` itself is gitignored and must never be committed in plaintext.
+DATABASE_URL=postgres://localhost:5432/myapp
+API_KEY=replace-me

data/.envrc

@@ -0,0 +1 @@
+PATH_add bin

data/.relaxed_rubocop.yml

@@ -0,0 +1,153 @@
+# Relaxed.Ruby.Style
+## Version 2.5
+
+Style/Alias:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylealias
+
+Style/AsciiComments:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styleasciicomments
+
+Style/BeginBlock:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylebeginblock
+
+Style/BlockDelimiters:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styleblockdelimiters
+
+Style/CommentAnnotation:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylecommentannotation
+
+Style/Documentation:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styledocumentation
+
+Layout/DotPosition:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#layoutdotposition
+
+Style/DoubleNegation:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styledoublenegation
+
+Style/EndBlock:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styleendblock
+
+Style/FormatString:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styleformatstring
+
+Style/IfUnlessModifier:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styleifunlessmodifier
+
+Style/Lambda:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylelambda
+
+Style/ModuleFunction:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylemodulefunction
+
+Style/MultilineBlockChain:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylemultilineblockchain
+
+Style/NegatedIf:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylenegatedif
+
+Style/NegatedWhile:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylenegatedwhile
+
+Style/NumericPredicate:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylenumericpredicate
+
+Style/ParallelAssignment:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styleparallelassignment
+
+Style/PercentLiteralDelimiters:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylepercentliteraldelimiters
+
+Style/PerlBackrefs:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styleperlbackrefs
+
+Style/Semicolon:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylesemicolon
+
+Style/SignalException:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylesignalexception
+
+Style/SingleLineBlockParams:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylesinglelineblockparams
+
+Style/SingleLineMethods:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylesinglelinemethods
+
+Layout/SpaceBeforeBlockBraces:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#layoutspacebeforeblockbraces
+
+Layout/SpaceInsideParens:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#layoutspaceinsideparens
+
+Style/SpecialGlobalVars:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylespecialglobalvars
+
+Style/StringLiterals:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylestringliterals
+
+Style/TrailingCommaInArguments:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styletrailingcommainarguments
+
+Style/TrailingCommaInArrayLiteral:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styletrailingcommainarrayliteral
+
+Style/TrailingCommaInHashLiteral:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#styletrailingcommainhashliteral
+
+Style/SymbolArray:
+  Enabled: false
+  StyleGuide: http://relaxed.ruby.style/#stylesymbolarray
+
+Style/WhileUntilModifier:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylewhileuntilmodifier
+
+Style/WordArray:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#stylewordarray
+
+Lint/AmbiguousRegexpLiteral:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#lintambiguousregexpliteral
+
+Lint/AssignmentInCondition:
+  Enabled: false
+  StyleGuide: https://relaxed.ruby.style/#lintassignmentincondition
+
+Layout/LineLength:
+  Enabled: false
+
+Metrics:
+  Enabled: false
+

data/.sops.yaml

@@ -0,0 +1,6 @@
+# Managed by sopsy. Maps encrypted files to their age recipients.
+creation_rules:
+  - path_regex: '\.env\.encrypted$'
+    age: 'age1se1qd8tpc9v42uuqz974uxx84mdz0aejujrzssmyjl6fvmwgx3gm62wjjxjyws'
+  - path_regex: '\.encrypted$'
+    age: 'age1se1qd8tpc9v42uuqz974uxx84mdz0aejujrzssmyjl6fvmwgx3gm62wjjxjyws'

data/.sopsy.sha

@@ -0,0 +1 @@
+b95fff7b1445f7690843e41678e2676916ec792390828e5755e7ec554812aece

data/.sopsy.yml

@@ -0,0 +1,11 @@
+recipients:
+- name: admin
+  public_key: age1se1qd8tpc9v42uuqz974uxx84mdz0aejujrzssmyjl6fvmwgx3gm62wjjxjyws
+  username: kig
+  break_glass: false
+encrypted_globs:
+- '*.encrypted'
+- .env.encrypted
+- config/*.encrypted.yaml
+sops_version: 3.13.2
+join_request_ttl: 72h

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/exe/inquirex

@@ -5,8 +5,9 @@
 # binary; this gem owns the bare name so cross-family tooling has one entry
 # point and no two gems install a binary called `inquirex`.
 #
-#   inquirex versions             # lockstep parity across the family
-#   inquirex versions --set 0.8.0
+#   inquirex versions-check              # lockstep parity across the family
+#   inquirex versions-check --preflight  # parity plus git release readiness
+#   inquirex versions-bump 0.8.0         # move every lockstep package
 #   inquirex changelogs
 #
 # Inside a checkout, prefer the repo's own Gemfile over whatever rubygems has

data/exe/inquirexor

@@ -0,0 +1 @@
+inquirex

data/justfile

@@ -0,0 +1,158 @@
+# Tell 'just' to run bash, source our setup script, then execute the recipe
+set shell := ["bash", "-c"]
+
+version := `grep VERSION lib/inquirex/tools/version.rb | awk '{print $3}' | tr -d '"' | tr -d '\n'`
+rbenv   := 'eval "$(rbenv init - bash)"; bundle exec '
+repo    := 'git@github.com:inquirex/inquirex-tools.git'
+
+# 1Password secret reference for the RubyGems TOTP, and the full path to `op`
+# because a recipe does not inherit an interactive shell's PATH.
+# The account is NOT named here: it is a private 1Password address and this
+# file is public. `op` reads it from OP_ACCOUNT, exported by the ecosystem
+# root's .envrc, which lives outside every repo. Two accounts are
+# registered and only one holds the open-source-repos vault, so without
+# OP_ACCOUNT the read can resolve against the wrong one, return nothing,
+# and publish silently falls back to prompting mid-release.
+op      := '/opt/homebrew/bin/op'
+otp_ref := 'op://open-source-repos/ruby-gems/one-time password?attribute=otp'
+
+gem_name := 'inquirex-tools'
+gem_file := 'pkg/' + gem_name + '-' + version + '.gem'
+gem_url  := 'https://rubygems.org/gems/' + gem_name
+
+[no-exit-message]
+recipes:
+    just --choose
+
+# Sync all dependencies
+install:
+    bin/setup
+
+build: install
+
+# Lint and reformat files
+lint:
+    {{ rbenv }} rubocop
+
+# Lint and reformat files (-a) — pass -A as an argument
+format *args:
+    {{ rbenv }} rubocop -a {{ args }}
+    /usr/bin/find . -name '*.md' -exec mdformat --wrap no {} \; -print
+
+# Run all the tests
+test *args: 
+    export ENVIRONMENT=test; {{ rbenv }} rspec {{args}}
+
+# Run tests with coverage
+test-coverage *args:
+    export ENVIRONMENT=test; export COVERAGE=true; {{ rbenv }} rspec {{ args }}
+
+ci: lint test-coverage 
+
+alias check-all := ci
+
+clean:
+    #!/usr/bin/env bash
+    @find . -name .DS_Store -delete -print || true
+    @rm -rf tmp/*
+
+# Run all lefthook pre-commit hooks
+lefthook:
+    {{ rbenv }} lefthook run pre-commit --all-files
+
+# Print current gem version
+version:
+    @echo "{{ version }}"
+
+# Clobber
+clobber: 
+    {{ rbenv }} rake clobber
+
+# Generate documentation
+doc: 
+    #!/usr/bin/env bash
+    {{ rbenv }} rake doc
+
+# `gem push` rather than `rake release`: release also guards the tree, tags and
+# pushes git — which `just release` does deliberately and separately — and it
+# gives no way to pass a 2FA code, so it always stopped to prompt.
+#
+# The code comes from 1Password unless one is passed in:
+#
+#   just publish            # read the code from 1Password
+#   just publish 123456     # use this code
+#
+# `just publish-all` in inquirex-tools passes one, because a TOTP is single-use:
+# four gems reading the same 30-second window would have the second push
+# rejected as a replay.
+#
+# Build the .gem and push it to RubyGems, non-interactively
+publish otp="": build
+    #!/usr/bin/env bash
+    set -euo pipefail
+    eval "$(rbenv init - bash 2>/dev/null || true)"
+
+    mkdir -p pkg
+    gem build {{ gem_name }}.gemspec --output "{{ gem_file }}"
+
+    # `|| true` is load-bearing: under `set -e` a failed `op read` — not signed
+    # in to 1Password, item renamed, op not installed — would abort the recipe
+    # before the prompting fallback below could run.
+    otp="{{ otp }}"
+    [[ -n "${otp}" ]] || otp=$({{ op }} read "{{ otp_ref }}" 2>/dev/null || true)
+
+    if [[ -n "${otp}" ]]; then
+      gem push "{{ gem_file }}" --otp "${otp}"
+    else
+      echo "rubygems: no OTP available — gem push will prompt if 2FA is required."
+      gem push "{{ gem_file }}"
+    fi
+
+    # Only reachable when the push succeeded: `set -e` aborts the recipe on a
+    # non-zero `gem push`, so the page never opens for a release that failed.
+    echo "published {{ gem_name }} {{ version }} → {{ gem_url }}"
+    open "{{ gem_url }}" 2>/dev/null || xdg-open "{{ gem_url }}" 2>/dev/null || true
+
+# Publish every package in the family, gems and npm packages alike.
+#
+# A thin wrapper: the ordering, the per-gem 2FA code and the stop-on-failure
+# rule all live in Inquirex::Tools::Publisher, where they are unit-tested. This
+# recipe only supplies the environment — OP_ACCOUNT, decrypted from
+# .env.encrypted — that the Ruby side cannot obtain for itself.
+#
+# Only this repo carries the sopsy setup. Each package's `just publish` runs as
+# a grandchild process and inherits the exported value, so the other five repos
+# stay free of an encrypted env and a Touch ID prompt they do not need.
+#
+#   just publish-all              # publish for real
+#   just publish-all --dry-run    # print the commands, run nothing
+#
+# Publish every package in the family (--dry-run to preview)
+publish-all *args:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    eval "$(rbenv init - bash 2>/dev/null || true)"
+
+    # `|| true`: a missing key, a locked Secure Enclave or no sopsy at all must
+    # not abort a release. Without OP_ACCOUNT the run still works — `op` falls
+    # back to the default account, and failing that, prompts.
+    if [[ -f .env.encrypted ]]; then
+      if secrets=$(sopsy decrypt .env.encrypted 2>/dev/null); then
+        set -a
+        eval "$(printf '%s\n' "${secrets}" | sed -E '/^#/d; /^$/d')"
+        set +a
+        echo "sopsy: OP_ACCOUNT=${OP_ACCOUNT:-<unset>}"
+      else
+        echo "sopsy: could not decrypt .env.encrypted — continuing without OP_ACCOUNT" >&2
+      fi
+    fi
+
+    bundle exec exe/inquirex publish {{ args }}
+
+# Tag v{{ version }}, publish the GH release, & refresh the Homebrew tap.
+release:
+    git fetch --tags
+    git tag -f "v{{ version }}"
+    git push -f --tags
+    gh release delete -y "v{{ version }}" --repo {{ repo }} 2>/dev/null || true
+    gh release create "v{{ version }}" --generate-notes --repo {{ repo }}

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/changelogs.rb

@@ -7,12 +7,14 @@ module Inquirex
       class Changelogs < Dry::CLI::Command
         desc "Regenerate CHANGELOG.md from merged PRs"
 
-        argument :repos, type: :array, required: false,
-                         desc: "Repositories to regenerate (default: all configured)"
+        argument :repos,
+          type:     :array,
+          required: false,
+          desc:     "Repositories to regenerate (default: all configured)"
 
         example [
           "                    # every repo with a .github_changelog_generator",
-          "inquirex-js         # just one"
+          "inquirex-widget     # just one"
         ]
 
         # The GitHub token comes from `gh auth token`, so no secret is stored