hecks 2.7.0 → 2.8.0

data/lib/hecks/projections/deploy/fargate.rb

@@ -324,7 +324,7 @@ module Hecks
           # Built outside the template heredoc so Layout/HeredocIndentation
           # cannot re-indent YAML that must match SessionSecretRead / env.
           # First interpolated line sits at the `\#{...}` column; later lines
-          # get that same left pad (lambda.rb's own OAUTHPOLICY pattern).
+          # get that same left pad (lambda.rb's own `OAUTHPOLICY` pattern).
           oauth_task_policy_yaml = google_oauth_present ? <<~OAUTHPOLICY.rstrip : ""
             - PolicyName: GoogleOauthSecretRead
               PolicyDocument:

data/lib/hecks/projections/deploy/lambda.rb

@@ -148,7 +148,7 @@ module Hecks
           # `stack_name` at all. They diverge on purpose for a domain whose
           # declared identity (`Hecks.bluebook`, hence `world.domain`, hence
           # `.world`'s own filename — `domain_name` above, needed just to find
-          # that file) no longer matches its live AWS stack's own name: a
+          # that file) does not match its live AWS stack's own name: a
           # CloudFormation stack cannot be renamed in place, and this domain's
           # logical ids are already load-bearing on a real RDS instance other
           # domains borrow from in Shared mode (see `owner_stack_name` below) —
@@ -1246,7 +1246,7 @@ module Hecks
             template_yaml = template_yaml.sub(
               /^        - LambdaInvokePolicy:\n            FunctionName: !Ref #{Regexp.escape(logical_id)}\n/, ""
             )
-            # Outputs — no `#{logical_id}Url` exists any more for `FunctionUrl` to
+            # Outputs — no `#{logical_id}Url` exists for `FunctionUrl` to
             # `!GetAtt`; WebFunction's own URL becomes the stack's one and only
             # "FunctionUrl" (never "WebFunctionUrl" — that name is reserved for
             # the two-URL case, a domain that also has a #{logical_id} of its
@@ -2287,7 +2287,7 @@ bastion_yaml = shared ? nil : Shared.bastion_yaml(
           reindent = ->(text) { text.each_line.map { |line| line.strip.empty? ? line : "  #{line}" }.join }
 
           # Not pre-reindented (unlike the return value as a whole, below) — each
-          # is spliced back into the still-being-dedented RESOURCES heredoc via
+          # is spliced back into the still-being-dedented `RESOURCES` heredoc via
           # `#{...}`, which the outer `reindent.call` already shifts by 2
           # spaces once; reindenting here too would double it.
           origin_access_control = use_oac ? <<~OAC : ""

data/lib/hecks/projections/reference.rb

@@ -1,7 +1,13 @@
-require_relative "../doc/reference"
 require_relative "../projector"
 
 module Hecks
+  # Repository-only tooling: `Doc::Reference` reads the committed pages under
+  # `docs/`, which only a checkout has, so it loads on first use and the
+  # packaged gem leaves it out (ADR 0066).
+  module Doc
+    autoload :Reference, File.expand_path("../doc/reference", __dir__)
+  end
+
   module Projections
     # The DSL reference pages, projected from the chapter's own Syntax
     # aggregate — the tables come from the declaration, the prose is

data/lib/hecks/projector/exporter.rb

@@ -263,10 +263,10 @@ module Hecks
       # nothing this domain attaches provides payment_connection.
       # @param registry [Runtime::Registry] the booted registry `domain_name` is loaded in
       # @param domain_name [String] the domain to export the payment-connection binding for
-      # @return [Hash{Symbol => String, nil}] `:provider` (name), one qualified verb per contract key
-      #   (`:connect`, `:reconnect`, `:disconnect`, `:suspend`, `:resume`, `:enable`, `:disable`) and
-      #   `:aggregate` (`:connect`'s own leading qualified aggregate name); `{}` if nothing this
-      #   domain attaches provides payment_connection
+      # @return [Hash{Symbol => String, nil}] `:provider` (name), one qualified verb per
+      #   contract key (`:connect`, `:reconnect`, `:disconnect`, `:suspend`, `:resume`,
+      #   `:enable`, `:disable`) and `:aggregate` (`:connect`'s own leading qualified
+      #   aggregate name); `{}` if nothing this domain attaches provides payment_connection
       def payment_connection(registry, domain_name)
         provider = registry.payment_connection_provider_for(domain_name)
         return {} unless provider

data/lib/hecks/projector/target.rb

@@ -59,7 +59,7 @@ module Hecks
       # rather than as a `raise` in the projection's own body, so the
       # requirement is stated instead of written as behaviour. The
       # registry refuses before the projection runs, so the projection
-      # itself no longer carries a guard about its own admission.
+      # itself carries no guard about its own admission.
       # `emits:` says what kind of artifact comes back.
       #
       # `:artifact` (the default) is one thing — a Hash, or a String.

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

@@ -0,0 +1,96 @@
+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.
+      #
+      # The clock and the pause are injected, so a spec runs the whole wait
+      # without sleeping.
+      class CiPublisher
+        WORKFLOW = ".github/workflows/publish-client.yml".freeze
+        INTERVAL = 15
+        LIMIT = 600
+
+        # @param root [String] the repository root
+        # @param published [Published] asks npm whether the version is out
+        # @param console [Console] progress output
+        # @param pause [#call] sleeps for a number of seconds
+        # @param now [#call] answers the current time in seconds, monotonically
+        def initialize(root:, published:, console:, pause:, now:)
+          @root = root
+          @published = published
+          @console = console
+          @pause = pause
+          @now = now
+        end
+
+        # Says whether the checkout carries the workflow that publishes the client.
+        #
+        # @return [Boolean] true when `.github/workflows/publish-client.yml` exists
+        def workflow?
+          File.exist?(File.join(@root, WORKFLOW))
+        end
+
+        # Tells the person CI publishes, then waits for the version to reach npm.
+        #
+        # @param version [String] the version being released
+        # @param dry_run [Boolean] say what would happen and wait for nothing
+        # @param wait [Boolean] false to report and return without polling
+        # @return [Boolean] false only when the wait timed out; true when the version appeared or
+        #   nothing was waited for
+        def wait!(version, dry_run:, wait:)
+          @console.say("CI publishes @hecks/client #{version} from the tag (#{WORKFLOW}); nothing is published from here.")
+          return true.tap { preview } if dry_run
+          return true.tap { skip_wait(version) } unless wait
+
+          @console.say("Waiting for @hecks/client #{version} on npm (every #{INTERVAL}s, up to #{LIMIT / 60} minutes)...")
+          arrived = arrives?(version)
+          @console.say("@hecks/client #{version} is on npm.") if arrived
+          arrived
+        end
+
+        # The hint printed when the wait ends without the version on npm.
+        #
+        # @param version [String] the version being released
+        # @return [String] how to look at, re-run and fall back from the CI publish
+        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."
+        end
+
+        private
+
+        def preview
+          @console.say("Dry run: would wait up to #{LIMIT / 60} minutes for it to appear on npm.")
+        end
+
+        def skip_wait(version)
+          @console.say("Not waiting (--no-wait). Check the run: gh run list --workflow publish-client.yml; " \
+                       "npm view @hecks/client@#{version} version")
+        end
+
+        def arrives?(version)
+          deadline = @now.call + LIMIT
+          loop do
+            return true if out?(version)
+            return false if @now.call >= deadline
+
+            @pause.call(INTERVAL)
+          end
+        end
+
+        def out?(version)
+          @published.npm?(version)
+        rescue Refusal
+          false
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,68 @@
+require "open3"
+
+module Hecks
+  module Release
+    class Runner
+      # Raised when a command a release step runs exits non-zero or cannot start.
+      class CommandFailed < StandardError; end
+
+      # 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.
+      class Commands
+        # What a captured command printed and whether it succeeded.
+        #
+        # @!attribute [r] stdout
+        #   @return [String] standard output
+        # @!attribute [r] stderr
+        #   @return [String] standard error, or the reason the command could not start
+        # @!attribute [r] success
+        #   @return [Boolean] true when the command exited zero
+        Result = Struct.new(:stdout, :stderr, :success, keyword_init: true) do
+          # Says whether the command exited zero.
+          #
+          # @return [Boolean] true when it did
+          def success?
+            success
+          end
+        end
+
+        # Runs a command and returns what it printed, whatever its exit status.
+        #
+        # @param argv [Array<String>] the command and its arguments, never a shell string
+        # @param env [Hash{String => String, nil}] variables to set, or unset with nil
+        # @param chdir [String, nil] the directory to run in; the current one when nil
+        # @return [Result] the output and status; a command that cannot start is a failed result
+        def capture(*argv, env: {}, chdir: nil)
+          stdout, stderr, status = Open3.capture3(env, *argv, **directory(chdir))
+          Result.new(stdout: stdout, stderr: stderr, success: status.success?)
+        rescue SystemCallError => e
+          Result.new(stdout: "", stderr: e.message, success: false)
+        end
+
+        # Runs a command with its output going straight to the terminal.
+        #
+        # @param argv [Array<String>] the command and its arguments, never a shell string
+        # @param env [Hash{String => String, nil}] variables to set, or unset with nil
+        # @param chdir [String, nil] the directory to run in; the current one when nil
+        # @return [true] when the command exits zero
+        # @raise [CommandFailed] if the command exits non-zero or cannot start
+        def run!(*argv, env: {}, chdir: nil)
+          return true if system(env, *argv, **directory(chdir))
+
+          raise CommandFailed, "`#{argv.first(2).join(' ')}` failed"
+        end
+
+        private
+
+        def directory(chdir)
+          chdir ? { chdir: chdir } : {}
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,52 @@
+module Hecks
+  module Release
+    class Runner
+      # Talks to the person running the release: progress lines, warnings and the
+      # y/N questions that come before anything irreversible.
+      class Console
+        # @param input [IO] where answers are read from
+        # @param out [IO] where progress goes
+        # @param err [IO] where refusals and failures go
+        # @param assume_yes [Boolean] answer every question yes without asking
+        def initialize(input:, out:, err:, assume_yes: false)
+          @input = input
+          @out = out
+          @err = err
+          @assume_yes = assume_yes
+        end
+
+        # Prints a progress line.
+        #
+        # @param text [String] the line
+        # @return [void]
+        def say(text)
+          @out.puts(text)
+        end
+
+        # Prints a refusal or failure line.
+        #
+        # @param text [String] the line
+        # @return [void]
+        def warn(text)
+          @err.puts(text)
+        end
+
+        # Asks a yes/no question, defaulting to no.
+        #
+        # @param question [String] what will happen if the answer is yes
+        # @return [Boolean] true for `y` or `yes`, or always under `assume_yes`; false on anything
+        #   else, including a closed input
+        def confirm?(question)
+          if @assume_yes
+            say("#{question} yes (--yes)")
+            return true
+          end
+
+          @out.print("#{question} [y/N] ")
+          @out.flush
+          %w[y yes].include?(@input.gets.to_s.strip.downcase)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+require "fileutils"
+require_relative "commands"
+
+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.
+      class GemPublisher
+        # @param root [String] the repository root
+        # @param commands [#run!] runs the build and the push
+        # @param console [Console] progress output
+        def initialize(root:, commands:, console:)
+          @root = root
+          @commands = commands
+          @console = console
+        end
+
+        # Pushes the gem, or with `dry_run` only builds it.
+        #
+        # @param version [String] the version being released
+        # @param dry_run [Boolean] build and delete the gem, pushing nothing
+        # @return [void]
+        # @raise [CommandFailed] if the build or the push fails
+        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)
+        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"))
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,48 @@
+require "hecks/vendoring/git_environment"
+require_relative "commands"
+
+module Hecks
+  module Release
+    class Runner
+      # The release's view of the repository: git run in the checkout, with the
+      # repository-pinning environment variables a git hook exports unset.
+      class Git
+        # @param root [String] the repository root
+        # @param commands [#capture, #run!] runs the git commands
+        def initialize(root:, commands:)
+          @root = root
+          @commands = commands
+        end
+
+        # Runs a git command and returns what it printed.
+        #
+        # @param args [Array<String>] git's arguments
+        # @return [String] standard output
+        # @raise [Refusal] if git exits non-zero
+        def read(*args)
+          result = capture(*args)
+          raise Refusal, "git #{args.first} failed: #{result.stderr.strip}" unless result.success?
+
+          result.stdout
+        end
+
+        # Runs a git command and returns the result whatever its status.
+        #
+        # @param args [Array<String>] git's arguments
+        # @return [Commands::Result] output and status
+        def capture(*)
+          @commands.capture("git", *, env: Vendoring::GitEnvironment.clean, chdir: @root)
+        end
+
+        # Runs a git command that changes something, showing its output.
+        #
+        # @param args [Array<String>] git's arguments
+        # @return [true] when git exits zero
+        # @raise [CommandFailed] if git exits non-zero
+        def run!(*)
+          @commands.run!("git", *, env: Vendoring::GitEnvironment.clean, chdir: @root)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,89 @@
+require "tempfile"
+require_relative "commands"
+
+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
+        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
+        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)
+          else
+            @console.say("Publishing @hecks/client #{version} to npm (1Password will prompt for Touch ID)...")
+            @console.say(APPROVAL_NOTICE)
+            publish_with_token
+          end
+        end
+
+        private
+
+        def package_dir
+          File.join(@root, PACKAGE_DIR)
+        end
+
+        def install_dependencies
+          return if Dir.exist?(File.join(package_dir, "node_modules"))
+
+          @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!
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,119 @@
+require "json"
+require_relative "commands"
+require_relative "git"
+
+module Hecks
+  module Release
+    class Runner
+      # The checks that run before a release does anything: the tools are
+      # installed, the checkout is a clean, current `main`, the gem and the
+      # JavaScript client agree on a version, and the changelog names it.
+      #
+      # Every refusal says what to do about it.
+      class Preflight
+        # What the checks learned about the release.
+        #
+        # @!attribute [r] version
+        #   @return [String] the version `lib/hecks/version.rb` declares
+        # @!attribute [r] sha
+        #   @return [String] the commit `HEAD` points at, which is also `origin/main`
+        Facts = Struct.new(:version, :sha, keyword_init: true)
+
+        INSTALL_HINTS = {
+          "git"  => "install git",
+          "gem"  => "install Ruby, which ships gem",
+          "npm"  => "install Node.js: brew install node",
+          "curl" => "install curl",
+          "op"   => "install the 1Password CLI: brew install 1password-cli"
+        }.freeze
+        VERSION_LINE = /^\s*VERSION\s*=\s*"(?<version>[^"]+)"/
+        CLIENT_PACKAGE = "packages/hecks-client/package.json".freeze
+
+        # @param root [String] the repository root
+        # @param commands [#capture] runs the tool probes
+        # @param git [Git] the repository the release is cut from
+        # @param tools [Array<String>] the executables the release needs on PATH
+        def initialize(root:, commands:, git:, tools:)
+          @root = root
+          @commands = commands
+          @git = git
+          @tools = tools
+        end
+
+        # Runs every check.
+        #
+        # @return [Facts] the version and commit the release is cut from
+        # @raise [Refusal] on the first check that fails, naming the fix
+        def check!
+          check_tools
+          check_branch
+          check_current
+          check_clean
+          version = declared_version
+          check_client_version(version)
+          check_changelog(version)
+          Facts.new(version: version, sha: git("rev-parse", "HEAD").strip)
+        end
+
+        private
+
+        def check_tools
+          @tools.each do |tool|
+            next if @commands.capture(tool, "--version").success?
+
+            raise Refusal, "#{tool} not found on PATH; #{INSTALL_HINTS.fetch(tool, "install #{tool}")}"
+          end
+        end
+
+        def check_branch
+          branch = git("rev-parse", "--abbrev-ref", "HEAD").strip
+          return if branch == "main"
+
+          raise Refusal, "on branch #{branch}, not main; release from main: git checkout main"
+        end
+
+        def check_current
+          fetch = @git.capture("fetch", "origin")
+          raise Refusal, "git fetch origin failed (#{fetch.stderr.strip}); check the network and the remote" unless fetch.success?
+
+          head = git("rev-parse", "HEAD").strip
+          upstream = git("rev-parse", "origin/main").strip
+          return if head == upstream
+
+          raise Refusal, "main (#{head[0, 7]}) is not origin/main (#{upstream[0, 7]}); " \
+                         "merge the release PR, then git pull --ff-only"
+        end
+
+        def check_clean
+          return if git("status", "--porcelain").strip.empty?
+
+          raise Refusal, "the working tree has uncommitted changes; commit or discard them before releasing"
+        end
+
+        def declared_version
+          match = File.read(File.join(@root, "lib/hecks/version.rb")).match(VERSION_LINE)
+          raise Refusal, "lib/hecks/version.rb declares no VERSION; restore it" unless match
+
+          match[:version]
+        end
+
+        def check_client_version(version)
+          client = JSON.parse(File.read(File.join(@root, CLIENT_PACKAGE))).fetch("version")
+          return if client == version
+
+          raise Refusal, "packages/hecks-client is at #{client} but Hecks::VERSION is #{version}; bump the package first."
+        end
+
+        def check_changelog(version)
+          return if File.read(File.join(@root, "CHANGELOG.md")).match?(/^## \[#{Regexp.escape(version)}\]/)
+
+          raise Refusal, "CHANGELOG.md has no `## [#{version}]` heading; add the release entry in the release PR"
+        end
+
+        def git(*)
+          @git.read(*)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+require "json"
+require_relative "commands"
+
+module Hecks
+  module Release
+    class Runner
+      # Asks the registries whether a version is already out, so a re-run of the
+      # release skips what an earlier run finished.
+      #
+      # Neither question needs credentials.
+      class Published
+        GEM_VERSIONS_URL = "https://rubygems.org/api/v1/versions/hecks.json".freeze
+        NPM_PACKAGE = "@hecks/client".freeze
+
+        # @param root [String] the repository root
+        # @param commands [#capture] runs curl and npm
+        def initialize(root:, commands:)
+          @root = root
+          @commands = commands
+        end
+
+        # Says whether RubyGems lists the hecks gem at a version.
+        #
+        # @param version [String] the version to look for
+        # @return [Boolean] true when it is published
+        # @raise [Refusal] if RubyGems cannot be reached or answers with something unreadable
+        def gem?(version)
+          result = @commands.capture("curl", "-fsS", GEM_VERSIONS_URL, chdir: @root)
+          unless result.success?
+            raise 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 Refusal, "RubyGems answered with something other than a version list; re-run in a minute"
+        end
+
+        # Says whether npm lists @hecks/client at a version.
+        #
+        # @param version [String] the version to look for
+        # @return [Boolean] true when it is published
+        # @raise [Refusal] if npm fails for any reason other than the version not existing
+        def npm?(version)
+          result = @commands.capture("npm", "view", "#{NPM_PACKAGE}@#{version}", "version", chdir: @root)
+          return result.stdout.strip == version if result.success?
+          return false if result.stderr.include?("E404")
+
+          raise Refusal, "could not check npm for #{NPM_PACKAGE}@#{version} (#{result.stderr.strip.lines.first}); " \
+                         "check the network and re-run"
+        end
+      end
+    end
+  end
+end