hecks 2.8.0 → 3.0.0

data/lib/hecks/query_specification/field_path.rb

@@ -1,44 +1,20 @@
 module Hecks
   module QuerySpecification
-    # One reading of a dotted query-field path, shared by every place that
-    # would otherwise invent its own. Left to themselves they disagree: a
-    # reference interpreter doing a bare `record[field]` lookup silently
-    # matches nothing for a dotted path, an SQL side that splits dots but
-    # judges numericness from the first nested segment only quietly
-    # compares a two-level path as text, and a build seal walks the
-    # declaration graph a third way. Three implementations of "what does
-    # pizza.price_cents.cents mean" is two more than a language gets to
-    # have.
+    # One reading of a dotted query-field path, shared by every caller that walks one.
     #
-    # Two sides, deliberately in one file so they cannot drift:
-    #
-    #   dig(holder, field)        — value side: walk a record's held state,
-    #                               segment by segment, through Value
-    #                               objects and plain hashes alike.
-    #   leaf_attribute / numeric? — declaration side: walk the declared
-    #                               shape to the attribute a path lands on.
-    #                               Callers supply value-object lookup as a
-    #                               block, because an Aggregate and a
-    #                               mid-build AggregateBuilder hold their
-    #                               shapes differently but walk the same.
+    # `dig` walks a record's held state; `leaf_attribute`/`numeric?` walk the declared shape.
     module FieldPath
       module_function
 
       NUMERIC_PRIMITIVES = %w[Integer Float].freeze
+      INTEGER_PRIMITIVES = %w[Integer].freeze
+      BOOLEAN_PRIMITIVES = %w[TrueClass FalseClass].freeze
       SCALAR_PRIMITIVES  = %w[String Integer Float TrueClass FalseClass].freeze
 
       # Reads the value a dotted field path names out of a record's held state.
       #
-      # The held value a dotted field names, or nil — never a raise. The
-      # first segment reads off the record (an Instance, a Value, or a
-      # plain row hash); the rest read through whatever each step holds. A
-      # stored nested value object is a plain hash by the time it is read
-      # back, keyed by symbol in memory and by string off a wire decode,
-      # so both spellings are tried — `key?` first, never `||`, because
-      # `||` falls through a genuinely-stored `false` to the other
-      # spelling (usually absent) and returns `nil` instead. The seal
-      # admits boolean leaves (`SCALAR_PRIMITIVES` below), so a `false`
-      # here is a real, held answer, not a missing one.
+      # Nested value objects come back as hashes keyed by symbol (memory) or string (wire),
+      # so both are tried, `key?` first: `||` would turn a stored `false` into `nil`.
       #
       # @param holder [Runtime::Instance, Runtime::Value, Hash, nil] the record, value
       #   object or row Hash the first segment is read from
@@ -52,8 +28,7 @@ module Hecks
         field.to_s.split(".").reduce(holder) { |current, segment| read(current, segment) }
       end
 
-      # Reads one path segment off whatever the previous step held — a single
-      # step of `dig`.
+      # Reads one path segment off whatever the previous step held.
       #
       # @param current [Runtime::Instance, Runtime::Value, Hash, Array, nil] the value the
       #   walk has reached; a Hash is tried by Symbol key, then by String key
@@ -68,14 +43,8 @@ module Hecks
           return current.key?(sym) ? current[sym] : current[segment]
         end
 
-        # M5 — "or nil, never raise" is this method's whole contract, and
-        # an Array broke it: `Array#[]` demands an Integer index, so
-        # `current[segment]` (a String) raised `TypeError` straight
-        # through `dig` instead of answering nil. A dotted path stepping
-        # into a list_of attribute (`where "tags.name" == "x"` against a
-        # bare list, rather than each element) has no single member a
-        # bare index would name anyway — nil is the honest answer, the
-        # same one a dangling reference or a missing key already gets.
+        # A list has no single member a String index could name; `Array#[]` would raise
+        # TypeError, breaking dig's "nil, never raise" contract.
         return nil if current.is_a?(Array)
 
         current[segment]
@@ -83,21 +52,16 @@ module Hecks
 
       # Walks the declared shape to the attribute a dotted path lands on.
       #
-      # The declared attribute a path lands on, or nil. `segments` is the
-      # dotted tail — for a bare field it is empty and the root attribute
-      # is its own leaf. The walk stops dead at a reference (an id is a
-      # scalar; nothing nests under it) and at any member the declared
-      # value object does not carry.
+      # `segments` is the dotted tail, empty for a bare field. The walk stops at a reference
+      # and at any member the declared value object does not carry.
       #
-      # @param attribute [Bluebook::Attribute, nil] the root attribute the path's first
-      #   segment names; `nil` (no such attribute) answers `nil`
+      # @param attribute [Bluebook::Attribute, nil] the root attribute; `nil` answers `nil`
       # @param segments [Array<String>] the path's remaining segments, `[]` for a bare field
       # @yield looks a value object up by name in the caller's own declarations
-      # @yieldparam type [String] the type name of the attribute being stepped into
-      # @yieldreturn [Class<Bluebook::ValueObject>, nil] the declared shape, or `nil` when
-      #   the type is not a value object the caller knows
-      # @return [Bluebook::Attribute, nil] the attribute at the end of the path; `nil` when
-      #   a step crosses a reference, an undeclared type or a member that does not exist
+      # @yieldparam type [String] the type name being stepped into
+      # @yieldreturn [Class<Bluebook::ValueObject>, nil] the declared shape, or `nil`
+      # @return [Bluebook::Attribute, nil] the leaf; `nil` when a step crosses a reference or
+      #   lands on an undeclared type or missing member
       def leaf_attribute(attribute, segments)
         current = attribute
         segments.each do |segment|
@@ -109,43 +73,39 @@ module Hecks
         current
       end
 
-      # Decides from the declared shape whether a field path holds a number.
+      # Whether a field path lands on one of `primitives`: itself, or (bare field only) a
+      # value object with a member typed as one.
       #
-      # May an ordered comparator (lt/lte/gt/gte) land here, and may an
-      # `ORDER BY` cast here numerically? A bare field keeps the one-level
-      # convention every adapter already implements: a numeric primitive,
-      # or a value object carrying at least one numeric member. A dotted
-      # path must land on a numeric primitive itself — the convention does
-      # not reach through a named path, it is the absence of one.
-      #
-      # @param attribute [Bluebook::Attribute, nil] the root attribute the path starts at;
-      #   `nil` answers `false`
+      # @param attribute [Bluebook::Attribute, nil] the root attribute; `nil` answers `false`
       # @param segments [Array<String>] the path's remaining segments, `[]` for a bare field
+      # @param primitives [Array<String>] the primitive type names that count as a match
       # @yield looks a value object up by name, as for `leaf_attribute`
-      # @yieldparam type [String] the type name to look up
-      # @yieldreturn [Class<Bluebook::ValueObject>, nil] the declared shape, or `nil`
-      # @return [Boolean] `true` when the leaf is an `Integer` or `Float`, or a bare field
-      #   naming a value object with at least one such member; `false` for a list, a
-      #   reference, or a path that lands nowhere
-      def numeric?(attribute, segments, &)
+      # @return [Boolean] `false` for a list, a reference, or a path that lands nowhere
+      def matches_primitive?(attribute, segments, primitives, &)
         leaf = leaf_attribute(attribute, segments, &)
         return false if leaf.nil? || leaf.list? || leaf.reference?
-        return true if NUMERIC_PRIMITIVES.include?(leaf.type.to_s)
+        return true if primitives.include?(leaf.type.to_s)
         return false unless segments.empty?
 
         shape = yield(leaf.type.to_s)
-        !shape.nil? && shape.attributes.any? { |member| NUMERIC_PRIMITIVES.include?(member.type.to_s) }
+        !shape.nil? && shape.attributes.any? { |member| primitives.include?(member.type.to_s) }
       end
 
-      # Decides whether a path ends on a scalar primitive that every engine
-      # compares the same way.
+      # @return [Boolean] whether a field path holds a number (`Integer` or `Float`)
+      def numeric?(attribute, segments, &) = matches_primitive?(attribute, segments, NUMERIC_PRIMITIVES, &)
+
+      # @return [Boolean] whether a field path holds specifically an `Integer` (not `Float`)
+      def integer?(attribute, segments, &) = matches_primitive?(attribute, segments, INTEGER_PRIMITIVES, &)
+
+      # @return [Boolean] whether a field path holds a `TrueClass`/`FalseClass`
+      def boolean?(attribute, segments, &) = matches_primitive?(attribute, segments, BOOLEAN_PRIMITIVES, &)
+
+      # Decides whether a path ends on a scalar primitive every engine compares alike.
       #
-      # A dotted path must end on a scalar member — landing on a value
-      # object would hand SQL a JSON object where the reference
-      # interpreter unwraps a hash, and the two would answer differently.
+      # A dotted path landing on a value object would give SQL a JSON object where the
+      # reference interpreter unwraps a hash, so the two would disagree.
       #
-      # @param attribute [Bluebook::Attribute, nil] the root attribute the path starts at;
-      #   `nil` answers `false`
+      # @param attribute [Bluebook::Attribute, nil] the root attribute; `nil` answers `false`
       # @param segments [Array<String>] the path's remaining segments, `[]` for a bare field
       # @yield looks a value object up by name, as for `leaf_attribute`
       # @yieldparam type [String] the type name to look up

data/lib/hecks/query_specification/hop_path.rb

@@ -2,61 +2,26 @@ require_relative "../naming"
 
 module Hecks
   module QuerySpecification
-    # One reading of a dotted query-field path that hops through a
-    # reference into another aggregate's own shape — FieldPath's
-    # sibling, not its member. FieldPath walks a shape, which cannot
-    # loop, and answers nil, never raising, because there is nothing
-    # left to say beyond "not found." HopPath walks the reference
-    # graph instead — `BluebookBuilder#validate_no_bidirectional_references!`
-    # refuses any reference cycle at declaration time (ADR 0025,
-    # "References" — widened from a direct pair to any ring, DFS over
-    # the chapter's own reference graph), so what's left to guard here
-    # is depth, not cycles: MAX_HOPS below, and this module's own
-    # `refusal` states for a target the chapter doesn't resolve. A walk
-    # here still needs to say why it stopped, not just that it did.
+    # One reading of a dotted query-field path that hops through a reference with `/`.
     #
-    # Every method below takes an attribute array, never a "shape"
-    # object — deliberately, because the two real callers hold their
-    # attributes differently. `AggregateBuilder` (tier-1 seal, mid-
-    # build) exposes `attributes` as a plain reader, but its own
-    # `attribute(name, type = String, ...)` is the DSL's attribute-
-    # declaring method — calling it as a finder would silently mint a
-    # new String attribute instead of looking one up. A sealed
-    # `Aggregate` (tier-2 seal, and every runtime target) has a
-    # real `attribute(name)` finder, but taking the array either way
-    # sidesteps the mismatch instead of asking every caller to know
-    # which kind of object it holds.
+    # Takes attribute arrays, not shapes: AggregateBuilder's `attribute(name)` declares rather
+    # than finds, so the two real callers cannot share a finder.
     module HopPath
       module_function
 
       Hop = Struct.new(:attribute, :target_name, :target, keyword_init: true)
 
-      # refusal: nil (clean), :unresolvable (a hop's target cannot be
-      # found — cross-domain, or simply not declared in this chapter),
-      # :too_deep (see MAX_HOPS below).
+      # `refusal` is nil when clean, `:unresolvable` when a hop's target is not found,
+      # `:too_deep` when the chain exceeds MAX_HOPS.
       Plan = Struct.new(:hops, :tail, :refusal, keyword_init: true)
 
-      # A hop chain long enough to matter is long enough to be a
-      # mistake — not a guard against a walk that cannot terminate.
-      # Nothing here loops forever regardless of how the reference
-      # graph is shaped: a hop chain is a literal dotted string, fixed
-      # at declaration time, and every step consumes exactly one of
-      # its own segments — the walk is bounded by what was typed, not
-      # by the graph. A self-referential aggregate hopping through
-      # itself more than once (`"parent.parent.name"`, a grandparent
-      # query) is real, common, and perfectly safe; this exists only
-      # to refuse a chain nobody meant to write this long.
+      # Bounds hop chains: a longer one is a mistake, not a runaway walk, since each
+      # step consumes one segment of the typed path.
       MAX_HOPS = 8
 
       # Names the path segment a reference attribute answers to.
       #
-      # The segment name a Reference answers to in a hop path — its own
-      # declared attribute name, unchanged (ADR 0025, "References":
-      # `reference_to` mints that bare name, no `_id`, so there is
-      # no derivation left to apply). `proposal/client` (a query hop)
-      # and `proposal.client` (the Ruby accessor,
-      # `Facade::Handle#define_reference_accessors`) name the same
-      # concept the same way.
+      # The attribute's own declared name, unchanged (ADR 0025).
       #
       # @param attribute [Bluebook::Attribute] a reference-typed attribute
       # @return [String] the attribute's declared name
@@ -65,17 +30,8 @@ module Hecks
       # Decides whether a field path starts by hopping through one of the given
       # references, without resolving the reference's target.
       #
-      # Does this path's head cross into another record via `/`? The
-      # operator is the answer now, not a name collision to arbitrate —
-      # `.` walks fields inside this record, `/` crosses into another
-      # one, so a path with no `/` is never a hop, full stop, and the
-      # old "a real local attribute wins first" rule (needed only
-      # because `.` was overloaded for both meanings, and `client_id`
-      # vs `client` was how the two were told apart) has nothing left
-      # to arbitrate. Answerable from `attributes` alone — a Reference
-      # knows its own `target_name` at declaration, before it can
-      # `resolve` it — which is what lets the aggregate seal recognise
-      # a hop it cannot yet check.
+      # A path with no `/` is never a hop: `.` walks fields inside a record, `/` crosses
+      # into another one.
       #
       # @param field [String, Symbol] the query field path, such as `:"client/status"`
       # @param attributes [Array<Bluebook::Attribute>] the attributes of the shape the path
@@ -91,17 +47,6 @@ module Hecks
 
       # Resolves the first hop of a field path and hands back what is left to walk.
       #
-      # **One step**: does `field`'s head hop through one of `attributes`'
-      # own references? Answers the resolved `Hop` plus the string
-      # still left to walk (itself possibly another `/`-hop, against
-      # the target's own attributes, or a plain `.`-dotted field walk
-      # once the hops run out) — or nil, when the head names nothing or
-      # the path has no `/` at all. This is the one primitive
-      # Runtime::ReferenceHop needs: it recurses hop by hop through its
-      # own `apply`, one ordinary same-aggregate query at a time, and
-      # never needs the whole chain resolved up front the way a seal
-      # does.
-      #
       # @param field [String, Symbol] the query field path, such as `"client/region/name"`
       # @param attributes [Array<Bluebook::Attribute>] the attributes of the shape the path
       #   starts from
@@ -124,11 +69,6 @@ module Hecks
       # Resolves every hop of a field path in order, stopping with a reason at
       # the first one it cannot follow.
       #
-      # The whole chain, resolved — every hop's target found, in
-      # order — for the one caller that needs it all at once:
-      # `BluebookBuilder#validate_query_hops!`, checking a hop chain
-      # before anything ever dispatches it.
-      #
       # @param field [String, Symbol] the query field path, such as `"client/region/name"`
       # @param attributes [Array<Bluebook::Attribute>] the attributes of the shape the path
       #   starts from
@@ -149,12 +89,8 @@ module Hecks
           hop, rest = step
           return Plan.new(hops: hops, tail: nil, refusal: :too_deep) if hops.size >= MAX_HOPS
 
-          # Pushed even unresolved — a caller reporting :unresolvable
-          # needs this hop's own target_name (real, known at
-          # declaration, regardless of whether resolve succeeded), not
-          # whatever hop came before it. `.target` is nil on this one
-          # entry; every caller checking `hops.last.target` already has
-          # to handle that, the same way `next_hop`'s own caller does.
+          # Pushed even unresolved: a caller reporting :unresolvable needs this hop's
+          # target_name, and `.target` is nil on this one entry.
           hops << hop
           return Plan.new(hops: hops, tail: nil, refusal: :unresolvable) unless hop.target
 

data/lib/hecks/release/gem_pin.rb

@@ -2,32 +2,8 @@ require_relative "gem_pin/published_versions"
 
 module Hecks
   module Release
-    # Finds the hecks version a project runs on, and refuses one that a
-    # stranger could not install.
-    #
-    # ## Why it exists
-    #
-    # A project that is copied out of its own workspace (handed to someone who
-    # will `bundle install` it, or built in an image with no sibling checkout)
-    # has to name a hecks release RubyGems actually publishes. A `path:` or
-    # `git:` source only works where the path or remote is reachable, and a
-    # version that was never published resolves nowhere. This reads the
-    # project's Gemfiles and lockfiles, without running Bundler, and says which
-    # version each pins or refuses.
-    #
-    # ## Resolution
-    #
-    # For each `Gemfile` under the root (a project can hold several, such as a
-    # domain and a helper app) the pin is, in order: the version its
-    # `Gemfile.lock` resolved, or the newest stable release its version
-    # constraint allows. Each pin must be published; the Gemfiles need not
-    # agree.
-    #
-    # ## Injectable network
-    #
-    # The published list comes from `published:`, any object answering
-    # `include?(version)` and `newest_satisfying(requirement)`. The default asks
-    # RubyGems; a caller without network hands in its own.
+    # Reads a project's Gemfiles and lockfiles (no Bundler run) and says which
+    # hecks version each pins, refusing any version RubyGems does not publish.
     class GemPin
       GEM_LINE = /^\s*gem\s+["']hecks["'](?<rest>.*)$/
       SOURCE_OPTION = /\b(?:path|git|github|gitlab|bitbucket|branch|ref|tag):/

data/lib/hecks/release/runner/ci_publisher.rb

@@ -3,13 +3,10 @@ require_relative "commands"
 module Hecks
   module Release
     class Runner
-      # The npm step when CI publishes: the release tag triggers
-      # `.github/workflows/publish-client.yml`, which publishes `@hecks/client`
-      # with npm trusted publishing, so nothing is published from this machine.
-      # This watches npm until the version appears.
+      # Watches npm for `@hecks/client` after CI publishes it via
+      # `.github/workflows/publish-client.yml` (npm trusted publishing).
       #
-      # The clock and the pause are injected, so a spec runs the whole wait
-      # without sleeping.
+      # Its clock and pause are injected, so a spec runs the wait without sleeping.
       class CiPublisher
         WORKFLOW = ".github/workflows/publish-client.yml".freeze
         INTERVAL = 15
@@ -60,8 +57,8 @@ module Hecks
         def self.timeout_hint(version)
           "Timed out after #{LIMIT / 60} minutes waiting for CI to publish @hecks/client #{version}. " \
             "See the run: gh run list --workflow publish-client.yml. Re-run it: " \
-            "gh workflow run publish-client.yml -f tag=v#{version}. Then finish with: bin/release --npm-only. " \
-            "To publish from this machine instead: bin/release --npm-only --npm-local."
+            "gh workflow run publish-client.yml -f tag=v#{version}. Then finish with: hecks publish --npm-only --confirm. " \
+            "To publish from this machine instead: hecks publish --npm-only --npm-local --confirm."
         end
 
         private

data/lib/hecks/release/runner/clean_tree.rb

@@ -0,0 +1,42 @@
+require_relative "commands"
+
+module Hecks
+  module Release
+    class Runner
+      # The check that what a release ships is exactly what is committed: nothing modified,
+      # untracked, or ignored under the paths the gem packages.
+      #
+      # `git status --porcelain` alone hides ignored files, and an ignored file under `lib/` or
+      # `rust/` is one a build of the gem could carry. Build output (`target/`) is ignored on
+      # purpose and never packaged, so it is not counted.
+      class CleanTree
+        # The repository paths the gem packages.
+        SHIPPED = %w[lib rust exe qa/settings.yml].freeze
+
+        # Ignored build output, which the gem leaves out.
+        BUILD_OUTPUT = %r{(\A|/)target/?\z}
+
+        # @param git [#read] runs a git command in the checkout and answers its output
+        def initialize(git:)
+          @git = git
+        end
+
+        # @return [Array<String>] each modified, untracked or ignored path under the packaged paths
+        def stray
+          lines = @git.read("status", "--porcelain", "--ignored", "--", *SHIPPED).lines.map(&:strip)
+          lines.reject(&:empty?).map { |line| line.sub(/\A\S+\s+/, "") }.grep_v(BUILD_OUTPUT)
+        end
+
+        # @return [void]
+        # @raise [Refusal] naming the first few stray paths
+        def check!
+          paths = stray
+          return if paths.empty?
+
+          raise Refusal, "#{paths.size} file(s) under #{SHIPPED.join(', ')} are modified, untracked or " \
+                         "ignored (#{paths.first(5).join(', ')}); commit or delete them before releasing"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/release/runner/commands.rb

@@ -9,10 +9,8 @@ module Hecks
       # Raised when a check refuses the release; the message names the fix.
       class Refusal < StandardError; end
 
-      # Runs the release's external commands: git, gem, npm, curl, op.
-      #
-      # The runner takes any object answering `capture` and `run!` the way this
-      # one does, so a spec hands in a recorder and never starts a real process.
+      # Runs the release's external commands (git, gem, npm, curl, op) through
+      # any object answering `capture`/`run!`, so a spec injects a recorder.
       class Commands
         # What a captured command printed and whether it succeeded.
         #

data/lib/hecks/release/runner/console.rb

@@ -15,6 +15,12 @@ module Hecks
           @assume_yes = assume_yes
         end
 
+        # @return [IO] where progress goes
+        attr_reader :out
+
+        # @return [IO] where refusals and failures go
+        attr_reader :err
+
         # Prints a progress line.
         #
         # @param text [String] the line

data/lib/hecks/release/runner/gem_publisher.rb

@@ -1,12 +1,14 @@
-require "fileutils"
 require_relative "commands"
+require_relative "clean_tree"
+require_relative "git"
+require_relative "../../cli/release_gem"
+require "hecks/hecks/adapters/codebase/gem_registry"
 
 module Hecks
   module Release
     class Runner
-      # The gem step: hands the push to `bin/release_gem`, which owns building the
-      # gem and pushing it with the key 1Password holds. A dry run builds the gem
-      # to prove it builds and deletes it.
+      # The gem step: hands the push to `Hecks::CLI::ReleaseGem`, which builds and pushes
+      # it with the key 1Password holds; a dry run only builds it, then deletes it.
       class GemPublisher
         # @param root [String] the repository root
         # @param commands [#run!] runs the build and the push
@@ -15,6 +17,7 @@ module Hecks
           @root = root
           @commands = commands
           @console = console
+          @registry = Hecks::Adapters::Codebase::GemRegistry.new(root: root, commands: commands)
         end
 
         # Pushes the gem, or with `dry_run` only builds it.
@@ -23,20 +26,23 @@ module Hecks
         # @param dry_run [Boolean] build and delete the gem, pushing nothing
         # @return [void]
         # @raise [CommandFailed] if the build or the push fails
+        # @raise [Refusal] if a packaged path holds a modified, untracked or ignored file
         def publish!(version, dry_run:)
           return build_only(version) if dry_run
 
-          @console.say("Publishing hecks #{version} to rubygems.org via bin/release_gem...")
-          @commands.run!(File.join(@root, "bin/release_gem"), chdir: @root)
+          CleanTree.new(git: Git.new(root: @root, commands: @commands)).check!
+
+          @console.say("Publishing hecks #{version} to rubygems.org...")
+          status = Hecks::CLI::ReleaseGem.call(root: @root, commands: @commands, out: @console.out,
+                                               err: @console.err, version: version)
+          raise CommandFailed, "the gem push was refused" unless status.zero?
         end
 
         private
 
         def build_only(version)
           @console.say("Dry run: building hecks-#{version}.gem (nothing is pushed)...")
-          @commands.run!("gem", "build", "hecks.gemspec", chdir: @root)
-        ensure
-          FileUtils.rm_f(File.join(@root, "hecks-#{version}.gem"))
+          @registry.build_only!(version)
         end
       end
     end

data/lib/hecks/release/runner/npm_publisher.rb

@@ -1,87 +1,43 @@
-require "tempfile"
 require_relative "commands"
+require "hecks/hecks/adapters/codebase/npm_registry"
 
 module Hecks
   module Release
     class Runner
       # The npm step: publishes `@hecks/client` from `packages/hecks-client`
       # with the token 1Password holds.
-      #
-      # `op run` resolves `release/npm_publish.env` into the environment of the
-      # one `npm publish` process. npm reads its token from a config file, so a
-      # throwaway user config holds a placeholder that npm expands from that
-      # environment; the file never contains the token and is deleted afterwards.
-      # The package's `prepack` builds `dist/`.
-      #
-      # The token is a granular one that bypasses two-factor authentication, because
-      # the account's second factor is a passkey. As a fallback the publish runs with
-      # `--auth-type=web` and its output is not captured, so if npm does ask for an
-      # approval it prints the link straight to the terminal and waits for it.
       class NpmPublisher
-        PACKAGE_DIR = "packages/hecks-client".freeze
-        ENV_FILE = "release/npm_publish.env".freeze
         APPROVAL_NOTICE = "npm will print an approval link; open it and approve with your security key or passkey. " \
                           "This step waits for you.".freeze
-        USERCONFIG_LINE = "//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}".freeze
 
-        # @param root [String] the repository root
-        # @param commands [#run!] runs npm and op
-        # @param console [Console] progress output
         def initialize(root:, commands:, console:)
           @root = root
-          @commands = commands
           @console = console
+          @registry = Hecks::Adapters::Codebase::NpmRegistry.new(root: root, commands: commands)
         end
 
-        # Publishes the package, or with `dry_run` only packs it.
-        #
-        # @param version [String] the version being released
-        # @param dry_run [Boolean] run `npm publish --dry-run`, which needs no credentials
-        # @return [void]
-        # @raise [CommandFailed] if installing, building or publishing fails
+        # Publishes the package, or with `dry_run` only packs it, which needs no
+        # credentials.
         def publish!(version, dry_run:)
           install_dependencies
           if dry_run
             @console.say("Dry run: npm publish --dry-run for @hecks/client #{version} (nothing is published)...")
-            @commands.run!("npm", "publish", "--dry-run", "--access", "public", chdir: package_dir)
+            @registry.dry_publish!
           else
             @console.say("Publishing @hecks/client #{version} to npm (1Password will prompt for Touch ID)...")
             @console.say(APPROVAL_NOTICE)
-            publish_with_token
+            @registry.publish!
           end
         end
 
         private
 
-        def package_dir
-          File.join(@root, PACKAGE_DIR)
-        end
-
+        # npm's `prepack` hook builds `dist/`; there is no separate build step here.
         def install_dependencies
-          return if Dir.exist?(File.join(package_dir, "node_modules"))
+          return if @registry.installed?
 
           @console.say("Installing the client's dependencies (npm ci)...")
-          @commands.run!("npm", "ci", chdir: package_dir)
-        end
-
-        def publish_with_token
-          with_userconfig do |userconfig|
-            @commands.run!(
-              "op", "run", "--env-file=#{File.join(@root, ENV_FILE)}", "--",
-              "npm", "publish", "--access", "public", "--auth-type=web", "--userconfig", userconfig,
-              chdir: package_dir
-            )
-          end
-        end
-
-        def with_userconfig
-          file = Tempfile.new(["hecks-npmrc", ".npmrc"])
-          file.chmod(0o600)
-          file.write("#{USERCONFIG_LINE}\n")
-          file.flush
-          yield file.path
-        ensure
-          file&.close!
+          @registry.install!
         end
       end
     end