hecks 2.8.0 → 3.0.0

data/lib/hecks/hecks/adapters/codebase/corpus_tasks.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require "hecks/corpus"
+require "hecks/query_ir"
+require "hecks/query_ir_mcp"
+require_relative "tree"
+require "hecks/rust_build"
+require_relative "../console_capture"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # What Codebase's `CorpusRun` asks of the working tree: which committed domains have a Rust
+      # feature, what the language's IR holds, and the two doors that serve it.
+      #
+      # The questions are pure reads and run in this process, with the code `hecks rust_domains` and
+      # `hecks ir_constructs` run (`Hecks::Corpus`, `Hecks::QueryIR`); the coverage question runs
+      # `Hecks::RustBuild`'s coverage tool over each generated module, also in this process. The
+      # two doors run until they are closed: the query MCP server on stdio, and the forms app on a
+      # local port.
+      module CorpusTasks
+        # Every operation this family carries out.
+        OPERATIONS = %w[serve_query_ir_mcp present].freeze
+
+        # The port `present` listens on when none is named.
+        DEFAULT_PORT = 4567
+
+        class << self
+          # @return [#call, nil] serves the MCP door; `Hecks::QueryIrMcp.start` when nil. A spec
+          #   replaces it so no stdio has to be held.
+          attr_accessor :mcp_server
+
+          # @return [#call, nil] takes `app:` and `port:` and serves until stopped; a WEBrick
+          #   server through Rack when nil.
+          attr_accessor :web_server
+
+          # @return [#capture, nil] runs each coverage check, as `capture(tool, argv, env:)`
+          #   answering an object with `out`, `err` and `ok?`; `Hecks::RustBuild` when nil.
+          attr_accessor :coverage_runner
+        end
+
+        module_function
+
+        # Opens one of the doors.
+        #
+        # @param operation [String] `serve_query_ir_mcp` or `present`
+        # @param held [Hash] the `CorpusRun` record's fields: `port`
+        # @param tree [Tree] the working tree, already known to be a hecks checkout
+        # @param shell [#capture, nil] unused
+        # @return [String] a note that the door closed
+        # @raise [ConsoleCapture::Failure] when the MCP door refuses the process's setup
+        def call(operation, held, tree, shell: nil)
+          _ = shell
+          return serve_mcp if operation == "serve_query_ir_mcp"
+
+          present(plain(held)[:port] || DEFAULT_PORT, tree)
+        end
+
+        # A pure read.
+        #
+        # @param operation [String] a query's name in snake case
+        # @param args [Hash] the query's plain arguments
+        # @param tree [Tree] the checkout
+        # @param shell [#capture, nil] unused; the coverage checks run in this process
+        # @return [String] the answer, one line for each row
+        # @raise [ConsoleCapture::Failure] when a coverage check fails, or a query is refused
+        def report(operation, args, tree, shell: nil)
+          _ = shell
+          case operation
+          when "rust_domains" then rust_domains(tree)
+          when "regen_order" then regen_order(tree)
+          when "corpus_rust_coverage" then coverage(tree)
+          else ir_query(operation, args)
+          end
+        end
+
+        # @param held [Hash] fields, each perhaps a value object's `{ value: x }`
+        # @return [Hash] the same fields as plain values
+        def plain(held) = held.transform_values { |value| value.is_a?(Hash) ? value[:value] : value }
+
+        # @return [String] a note that the MCP door closed
+        # @raise [ConsoleCapture::Failure] when the door refuses to start
+        def serve_mcp
+          server = CorpusTasks.mcp_server || ->(**options) { QueryIrMcp.start(**options) }
+          server.call(argv: [])
+          "query ir mcp door closed"
+        rescue SystemExit => e
+          raise ConsoleCapture::Failure, "the query ir mcp door refused to start (status #{e.status}); see stderr"
+        end
+
+        # @param port [Integer] the port to listen on
+        # @param tree [Tree] the checkout
+        # @return [String] a note that the server stopped
+        def present(port, tree)
+          require "hecks/forms/banking_presentation"
+          app = Forms::BankingPresentation.app(root: tree.root)
+          warn "banking forms, in memory, on http://localhost:#{port}/ - no authentication, no CSRF " \
+               "protection, no caller identity; do not expose beyond localhost"
+          (CorpusTasks.web_server || method(:rack_serve)).call(app: app, port: port)
+          "presented on port #{port}, now stopped"
+        end
+
+        # @param app [#call] the Rack app
+        # @param port [Integer] the port
+        # @return [void]
+        def rack_serve(app:, port:)
+          require "rackup"
+          Rackup::Server.start(app: app, Port: port, server: "webrick")
+        end
+
+        # @param tree [Tree] the checkout
+        # @return [String] each domain with a Rust feature: its feature, a tab, and its directory
+        def rust_domains(tree)
+          Corpus.rust_domains(root: tree.root).map { |domain| "#{domain.feature}\t#{tree.relative(domain.dir)}" }
+                .join("\n")
+        end
+
+        # @param tree [Tree] the checkout
+        # @return [String] the directories regeneration walks, in order, one for each line
+        def regen_order(tree)
+          Corpus.rust_regen_order(root: tree.root).map { |domain| tree.relative(domain.dir) }.join("\n")
+        end
+
+        # Runs the coverage tool over every generated module. A module named in
+        # `Corpus::RUST_COVERAGE_PENDING` must still fail; every other one must pass.
+        #
+        # @param tree [Tree] the checkout
+        # @return [String] one line for each module, and how many were checked
+        # @raise [ConsoleCapture::Failure] with every module that failed, or that passes now while
+        #   still listed as pending
+        def coverage(tree)
+          modules = Corpus.generated_modules(root: tree.root)
+          pending = Corpus::RUST_COVERAGE_PENDING
+          unknown = pending.keys - modules
+          raise ConsoleCapture::Failure, "pending names #{unknown.join(', ')}, with no generated module" if unknown.any?
+
+          lines, problems = judge(modules, pending, coverage_results(modules, tree))
+          raise ConsoleCapture::Failure, [*lines, "", *problems].join("\n") if problems.any?
+
+          [*lines, "#{modules.size} generated modules checked"].join("\n")
+        end
+
+        # @param modules [Array<String>] the generated modules
+        # @param pending [Hash{String => String}] the modules known to fail, and why
+        # @param results [Hash{String => Array}] each module's `[passed, output]`
+        # @return [Array(Array<String>, Array<String>)] the report lines and the problems
+        def judge(modules, pending, results)
+          problems = []
+          lines = modules.map do |name|
+            passed, output = results.fetch(name)
+            if pending.key?(name)
+              problems << "#{name} passes now - delete it from Hecks::Corpus::RUST_COVERAGE_PENDING" if passed
+              "#{name}: pending (#{passed ? 'NOW PASSES' : 'still fails'}) - #{pending[name]}"
+            else
+              problems << "#{name} failed:\n#{output}" unless passed
+              "#{name}: #{passed ? 'ok' : 'FAILED'}"
+            end
+          end
+          [lines, problems]
+        end
+
+        # @param modules [Array<String>] the generated modules
+        # @param tree [Tree] the checkout
+        # @return [Hash{String => Array}] each module's `[passed, output]`
+        def coverage_results(modules, tree)
+          runner = CorpusTasks.coverage_runner || RustBuild
+          env = { "HECKS_RUST_DIR" => tree.path("rust") }
+          modules.to_h do |name|
+            result = runner.capture("rust_coverage", [name], env: env)
+            [name, [result.ok?, [result.out, result.err].join]]
+          end
+        end
+
+        # @param operation [String] `ir_constructs`, `ir_duplicates` or `ir_impact`
+        # @param args [Hash] the query's plain arguments
+        # @return [String] the formatted answer
+        # @raise [ConsoleCapture::Failure] when the query refuses its arguments
+        def ir_query(operation, args)
+          case operation
+          when "ir_constructs" then QueryIR.format_constructs(QueryIR.constructs(words(args[:names])))
+          when "ir_duplicates" then duplicates(args)
+          else QueryIR.format_impact_preview(QueryIR.impact_preview(args[:name], args[:field]))
+          end
+        rescue ArgumentError => e
+          raise ConsoleCapture::Failure, e.message
+        end
+
+        # @param args [Hash] `domains` and `meta`
+        # @return [String] the duplicated rules; the meta-domain is included when asked for, or
+        #   when no domain is named
+        def duplicates(args)
+          domains = args[:domains] ? words(args[:domains]) : nil
+          QueryIR.format_duplicates(QueryIR.duplicates(domains: domains, include_meta: args[:meta] == true || domains.nil?))
+        end
+
+        # @param list [String, nil] a comma-separated list
+        # @return [Array<String>] its items
+        def words(list) = list.to_s.split(",").map(&:strip).reject(&:empty?)
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/codebase/gem_registry.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "hecks/release/runner/commands"
+require_relative "secret_vault"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # The `GemRegistry` adapter: what a release does with rubygems.org and the `gem` program.
+      #
+      # It asks the registry which versions are out (over `curl`, no credentials), builds the gem
+      # from the checkout's gemspec, and pushes it with the key the SecretVault holds. A built gem
+      # file is always deleted again, whether the push worked or not.
+      class GemRegistry
+        # Where RubyGems lists the published versions of the gem.
+        VERSIONS_URL = "https://rubygems.org/api/v1/versions/hecks.json"
+
+        # The env file `op run` reads the push key from, relative to the checkout.
+        ENV_FILE = "release/gem_push.env"
+
+        # @param root [String] the checkout's root
+        # @param commands [#capture, #run!] starts each process
+        # @param vault [SecretVault, nil] holds the push key; one over `commands` when nil
+        def initialize(root:, commands:, vault: nil)
+          @root = root
+          @commands = commands
+          @vault = vault || SecretVault.new(commands: commands)
+        end
+
+        # Says whether RubyGems lists the gem at a version.
+        #
+        # @param version [String] the version to look for
+        # @return [Boolean] true when it is published
+        # @raise [Hecks::Release::Runner::Refusal] when RubyGems cannot be reached or answers with
+        #   something that is not a version list
+        def published?(version)
+          result = @commands.capture("curl", "-fsS", VERSIONS_URL, chdir: @root)
+          unless result.success?
+            raise Release::Runner::Refusal, "could not list published hecks versions (#{result.stderr.strip}); " \
+                                            "check the network and re-run"
+          end
+
+          JSON.parse(result.stdout).any? { |entry| entry["number"] == version }
+        rescue JSON::ParserError
+          raise Release::Runner::Refusal, "RubyGems answered with something other than a version list; " \
+                                          "re-run in a minute"
+        end
+
+        # Builds the gem, to prove it builds, and deletes it again.
+        #
+        # @param version [String] the version being released
+        # @return [void]
+        # @raise [Hecks::Release::Runner::CommandFailed] when the build fails
+        def build_only!(version)
+          @commands.run!("gem", "build", "hecks.gemspec", chdir: @root)
+        ensure
+          discard(version)
+        end
+
+        # Builds the gem and pushes it to rubygems.org, then deletes the file.
+        #
+        # @param version [String] the version being released
+        # @return [void]
+        # @raise [Hecks::Release::Runner::CommandFailed] when the build or the push fails
+        def push!(version)
+          @commands.run!("gem", "build", "hecks.gemspec", chdir: @root)
+          @vault.run!(ENV_FILE, "gem", "push", "hecks-#{version}.gem", chdir: @root)
+        ensure
+          discard(version)
+        end
+
+        private
+
+        def discard(version) = FileUtils.rm_f(File.join(@root, "hecks-#{version}.gem"))
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/codebase/kernel_tables.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "tree"
+require "hecks/kernel_capabilities"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # What Codebase's `KernelRun` asks of the working tree: projecting the capability enums the
+      # hand-written Rust kernel is matched against, and checking that each capability the grammar
+      # admits has its hand-written file.
+      #
+      # The projection is built in memory by `KernelCapabilities`, the code
+      # `hecks project_kernel_capabilities` runs, and compared with the tree; it writes only when
+      # confirmed. The coverage check reads the tree and writes nothing.
+      module KernelTables
+        # Every operation this family carries out.
+        OPERATIONS = %w[project_kernel_capabilities measure_kernel_coverage].freeze
+
+        module_function
+
+        # Carries out one operation.
+        #
+        # @param operation [String] one of `OPERATIONS`
+        # @param held [Hash] the `KernelRun` record's fields
+        # @param tree [Tree] the working tree, already known to be a hecks checkout
+        # @param shell [#capture] unused; the family starts no child process
+        # @return [String] the drift report, or the coverage report
+        # @raise [ConsoleCapture::Failure] when a capability has no kernel file
+        def call(operation, held, tree, shell: nil)
+          _ = shell
+          confirm = (held[:confirm].is_a?(Hash) ? held[:confirm][:value] : held[:confirm]) == true
+          return coverage(tree) if operation == "measure_kernel_coverage"
+
+          result = KernelCapabilities.build(root: tree.root)
+          tree.apply(result.content, stale: result.stale, confirm: confirm)
+        end
+
+        # Lists every capability the live grammar admits with whether its file is there.
+        #
+        # @param tree [Tree] the checkout
+        # @return [String] one line for each capability, and a verdict
+        # @raise [ConsoleCapture::Failure] when any capability has no file
+        def coverage(tree)
+          lines, verdict, complete = KernelCapabilities.coverage_report(root: tree.root)
+          report = [lines, "", verdict].join("\n")
+          return report if complete
+
+          raise ConsoleCapture::Failure, report
+        end
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/codebase/language.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "tree"
+require_relative "../shell"
+require "hecks/projection_files"
+require "hecks/grammar/evolve"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # What Codebase's `LanguageRun` asks of the working tree: projecting the language's tables
+      # and walking a word through its lifecycle.
+      #
+      # A projection is built in memory by {ProjectionFiles} (the same code the `hecks project_*`
+      # scripts run) and compared with the tree; it writes only when confirmed. An evolution edits
+      # the syntax tables through {Grammar::Evolve}: unconfirmed it is rehearsed against an
+      # in-memory copy and reports the edit it would make; confirmed it regenerates the golden IR
+      # and holds the gates in a child process, and puts every file back if a gate refuses.
+      module Language
+        # The projection each operation runs.
+        PROJECTIONS = {
+          "project_model"             => :model,
+          "project_vocabulary"        => :vocabulary,
+          "project_rust_vocabulary"   => :rust_vocabulary,
+          "project_reserved_names"    => :reserved_names,
+          "project_parser_table"      => :parser_table,
+          "project_bootstrap_table"   => :bootstrap_table,
+          "project_field_hints"       => :field_hints,
+          "project_expression_tables" => :expression_tables,
+          "project_reference"         => :reference
+        }.freeze
+
+        # The status each word or argument operation moves a row to.
+        STATUSES = { "admit" => "admitted", "deprecate" => "deprecated", "retire" => "retired",
+                     "admit_argument" => "admitted", "deprecate_argument" => "deprecated",
+                     "retire_argument" => "retired" }.freeze
+
+        # Every operation this family carries out.
+        OPERATIONS = (PROJECTIONS.keys + %w[propose rename propose_argument] + STATUSES.keys).freeze
+
+        # The specs that hold a grammar edit: the syntax rows agree with the builder, the lifecycle
+        # holds, and the golden IR is the one the language produces.
+        GATES = %w[spec/syntax_conformance_spec.rb spec/syntax_lifecycle_spec.rb spec/ir_golden_spec.rb].freeze
+
+        # The golden IR a grammar edit regenerates.
+        GOLDEN = "spec/golden/ir/Bluebook.json"
+
+        # What the tool says after a proposal or a rename, which still needs hand work.
+        FOLLOW_UP = {
+          "propose"          => "Proposed. It reaches no projection until admitted. Before `hecks admit`:\n  " \
+                                "1. teach the %<context>s builder the word (and its spec/dsl_spec example)",
+          "rename"           => "Renamed. The old spelling keeps parsing — that is the point. Before this holds:\n  " \
+                                "1. alias the new word to the old in the %<context>s builder " \
+                                "(alias_method :%<new_name>s, :%<word>s)\n  " \
+                                "2. add the identical-IR example to spec/dsl_spec.rb",
+          "propose_argument" => "Proposed. It reaches no projection until admitted. Before " \
+                                "`hecks admit_argument`:\n  " \
+                                "1. teach the %<context>s builder's %<word>s method the argument"
+        }.freeze
+
+        module_function
+
+        # Carries out one operation.
+        #
+        # @param operation [String] one of `OPERATIONS`
+        # @param held [Hash] the `LanguageRun` record's fields
+        # @param tree [Tree] the working tree, already known to be a hecks checkout
+        # @param shell [#capture] starts the gates' child process
+        # @return [String] what was found, or done
+        # @raise [ConsoleCapture::Failure] when the language refuses the edit, or a gate does
+        def call(operation, held, tree, shell: Shell.new)
+          args = held.transform_values { |value| value.is_a?(Hash) ? value[:value] : value }
+          return project(operation, args, tree) if PROJECTIONS.key?(operation)
+
+          evolve(operation, args, tree, shell)
+        end
+
+        # Where every word stands: the rows not simply admitted, and the renamed ones.
+        #
+        # @return [String] a count, then a line for each row that is moving or renamed
+        def word_status
+          rows = Grammar::Evolve.keyword_rows
+          moving = rows.reject { |row| row[:status] == "admitted" }
+          renamed = rows.reject { |row| row[:was].to_s.empty? }
+          lines = ["#{rows.size} keyword rows; #{moving.size} not simply admitted; #{renamed.size} renamed"]
+          lines += moving.map { |row| "  #{row[:status].ljust(10)} #{row[:context]}.#{row[:word]}" }
+          lines += renamed.map { |row| "  renamed    #{row[:context]}.#{row[:word]} (was #{row[:was]})" }
+          lines.join("\n")
+        end
+
+        # @param operation [String] a projection's operation
+        # @param args [Hash] the record's plain fields
+        # @param tree [Tree] the checkout
+        # @return [String] the projected text for `stdout`, or the drift report
+        # @raise [ConsoleCapture::Failure] when the language cannot be projected
+        def project(operation, args, tree)
+          result = ProjectionFiles.build(PROJECTIONS.fetch(operation), root: tree.root)
+          return result.content.values.first if args[:stdout]
+
+          tree.apply(result.content, stale: result.stale, confirm: args[:confirm] == true)
+        rescue ProjectionFiles::Refused => e
+          raise ConsoleCapture::Failure, e.message
+        end
+
+        # @param operation [String] a word or argument operation
+        # @param args [Hash] the record's plain fields
+        # @param tree [Tree] the checkout
+        # @param shell [#capture] starts the gates
+        # @return [String] the rehearsed edit, or the confirmed edit's outcome
+        # @raise [ConsoleCapture::Failure] when the language or a gate refuses
+        def evolve(operation, args, tree, shell)
+          change = -> { edit(operation, args) }
+          return rehearse(change, tree) unless args[:confirm] == true
+
+          guarded(operation, args, tree, shell, change)
+        rescue Grammar::Evolve::Refusal => e
+          raise ConsoleCapture::Failure, e.message
+        end
+
+        # @param edit [#call] the edit to make
+        # @param tree [Tree] the checkout
+        # @return [String] each file the edit would change, with its lines added and removed
+        def rehearse(edit, tree)
+          changed = Grammar::Evolve.rehearse(&edit)
+          lines = changed.map do |path, text|
+            before = File.read(path).lines
+            after = text.lines
+            "  changed #{tree.relative(path)} (+#{(after - before).size} -#{(before - after).size} lines)"
+          end
+          ["dry run, #{changed.size} file changes (add --confirm to make them, regenerate the golden and hold the gates):",
+           *lines].join("\n")
+        end
+
+        # Makes the edit, regenerates the golden and holds the gates; puts every file back if the
+        # edit or a gate refuses.
+        #
+        # @param operation [String] the operation, for the follow-up it prints
+        # @param args [Hash] the record's plain fields
+        # @param tree [Tree] the checkout
+        # @param shell [#capture] starts the child processes
+        # @param edit [#call] the edit to make
+        # @return [String] what the gates held, and what is left to do by hand
+        # @raise [ConsoleCapture::Failure] when the edit or a gate refuses; nothing was changed
+        def guarded(operation, args, tree, shell, edit)
+          paths = Grammar::Evolve.syntax_paths + [tree.path(GOLDEN)]
+          snapshots = paths.to_h { |path| [path, File.read(path)] }
+          Grammar::Evolve.restore_on_raise(paths, &edit)
+          regenerate(tree, shell)
+          gates = shell.capture("bundle", "exec", "rspec", *GATES, chdir: tree.root)
+          unless gates.ok?
+            snapshots.each { |path, text| File.write(path, text) }
+            raise ConsoleCapture::Failure,
+                  "RESTORED — the gates refused, and the failures are the checklist. Nothing was " \
+                  "changed.\n#{[gates.out, gates.err].join.strip}"
+          end
+          ["#{args[:context]}.#{args[:word]} — the gates hold. Regenerated projections and the golden " \
+           "are in the tree.", follow_up(operation, args)].compact.join("\n")
+        end
+
+        # @param tree [Tree] the checkout
+        # @param shell [#capture] starts the child process
+        # @return [void]
+        def regenerate(tree, shell)
+          shell.capture("bundle", "exec", "rspec", "spec/ir_golden_spec.rb", env:   { "GOLDEN" => "rewrite" },
+                                                                             chdir: tree.root)
+        end
+
+        # @param operation [String] the operation
+        # @param args [Hash] the record's plain fields
+        # @return [String, nil] what still needs hand work, if anything
+        def follow_up(operation, args)
+          text = FOLLOW_UP[operation] or return nil
+
+          format(text, context: args[:context], new_name: args[:new_name], word: args[:word])
+        end
+
+        # Makes one edit to the syntax tables.
+        #
+        # @param operation [String] a word or argument operation
+        # @param args [Hash] the record's plain fields
+        # @return [void]
+        # @raise [Grammar::Evolve::Refusal] when the tables refuse the edit
+        def edit(operation, args)
+          case operation
+          when "propose" then propose(args)
+          when "rename" then rename(args)
+          when "propose_argument" then propose_argument(args)
+          when "admit", "deprecate", "retire" then set_status(operation, args)
+          else set_argument_status(operation, args)
+          end
+        end
+
+        # @param args [Hash] the record's plain fields
+        # @return [void]
+        def propose(args)
+          Grammar::Evolve.propose(word: args[:word], context: args[:context], body: args[:body] || "none",
+                                  inner: args[:inner] || "", opens: args[:opens] || "", fills: args[:fills] || "")
+        end
+
+        # @param args [Hash] the record's plain fields
+        # @return [void]
+        # @raise [Grammar::Evolve::Refusal] when no new name was given
+        def rename(args)
+          to = args[:new_name] or refuse("a rename goes somewhere: new_name=")
+          Grammar::Evolve.rename(word: args[:word], context: args[:context], to: to)
+        end
+
+        # @param args [Hash] the record's plain fields
+        # @return [void]
+        def propose_argument(args)
+          Grammar::Evolve.propose_argument(keyword: args[:word], context: args[:context], kind: args[:kind],
+                                           required: args[:required] || "false", at: args[:at] || "",
+                                           named: args[:named] || "", fills: args[:fills] || "",
+                                           pairs_shape: args[:pairs_shape])
+        end
+
+        # @param operation [String] `admit`, `deprecate` or `retire`
+        # @param args [Hash] the record's plain fields
+        # @return [void]
+        def set_status(operation, args)
+          Grammar::Evolve.set_status(word: args[:word], context: args[:context], to: STATUSES.fetch(operation))
+        end
+
+        # @param operation [String] the argument form of `admit`, `deprecate` or `retire`
+        # @param args [Hash] the record's plain fields
+        # @return [void]
+        def set_argument_status(operation, args)
+          Grammar::Evolve.set_argument_status(keyword: args[:word], context: args[:context],
+                                              to: STATUSES.fetch(operation), at: args[:at] || "",
+                                              named: args[:named] || "")
+        end
+
+        # @param message [String] why the edit cannot be made
+        # @raise [Grammar::Evolve::Refusal] always
+        def refuse(message) = raise(Grammar::Evolve::Refusal, message)
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/codebase/npm_registry.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "tempfile"
+require "hecks/release/runner/commands"
+require_relative "secret_vault"
+
+module Hecks
+  module Adapters
+    module Codebase
+      # The `NpmRegistry` adapter: what a release does with npm and the `@hecks/client` package.
+      #
+      # It asks npm whether a version is out (no credentials), installs the package's
+      # dependencies, and publishes it, either as a dry run (a pack, no credentials) or with the
+      # token the SecretVault holds. The token bypasses 2FA, so the publish runs with
+      # `--auth-type=web` and its output is not captured: the approval link reaches the terminal.
+      class NpmRegistry
+        # The package, by name.
+        PACKAGE = "@hecks/client"
+
+        # Where the package stands, relative to the checkout.
+        PACKAGE_DIR = "packages/hecks-client"
+
+        # The env file `op run` reads the publish token from, relative to the checkout.
+        ENV_FILE = "release/npm_publish.env"
+
+        # The npmrc line that reads the token from the environment `op run` sets.
+        USERCONFIG_LINE = "//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}"
+
+        # @param root [String] the checkout's root
+        # @param commands [#capture, #run!] starts each process
+        # @param vault [SecretVault, nil] holds the publish token; one over `commands` when nil
+        def initialize(root:, commands:, vault: nil)
+          @root = root
+          @commands = commands
+          @vault = vault || SecretVault.new(commands: commands)
+        end
+
+        # Says whether npm lists the package at a version.
+        #
+        # @param version [String] the version to look for
+        # @return [Boolean] true when it is published
+        # @raise [Hecks::Release::Runner::Refusal] when npm fails for any reason other than the
+        #   version not existing
+        def published?(version)
+          result = @commands.capture("npm", "view", "#{PACKAGE}@#{version}", "version", chdir: @root)
+          return result.stdout.strip == version if result.success?
+          return false if result.stderr.include?("E404")
+
+          raise Release::Runner::Refusal,
+                "could not check npm for #{PACKAGE}@#{version} (#{result.stderr.strip.lines.first}); " \
+                "check the network and re-run"
+        end
+
+        # @return [Boolean] whether the package's dependencies are already installed
+        def installed?
+          Dir.exist?(File.join(package_dir, "node_modules"))
+        end
+
+        # Installs the package's dependencies with `npm ci`.
+        #
+        # @return [void]
+        # @raise [Hecks::Release::Runner::CommandFailed] when it fails
+        def install!
+          @commands.run!("npm", "ci", chdir: package_dir)
+        end
+
+        # Packs the package and publishes nothing.
+        #
+        # @return [void]
+        # @raise [Hecks::Release::Runner::CommandFailed] when the pack fails
+        def dry_publish!
+          @commands.run!("npm", "publish", "--dry-run", "--access", "public", chdir: package_dir)
+        end
+
+        # Publishes the package with the token the vault holds.
+        #
+        # @return [void]
+        # @raise [Hecks::Release::Runner::CommandFailed] when the publish fails
+        def publish!
+          with_userconfig do |userconfig|
+            @vault.run!(File.join(@root, ENV_FILE), "npm", "publish", "--access", "public", "--auth-type=web",
+                        "--userconfig", userconfig, chdir: package_dir)
+          end
+        end
+
+        private
+
+        def package_dir = File.join(@root, PACKAGE_DIR)
+
+        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!
+        end
+      end
+    end
+  end
+end