hecks 3.11.0 → 3.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 130184b20d584f87b5ede5d45364b213c07677a3330fa198bee6680077ef1899
-  data.tar.gz: f60d730c4d1fc428703bdcc3dcd63f07ea10b77386e0eab4dcab12180e04cac4
+  metadata.gz: e1a1eacc3bae3f940928e23269c95e0306f291ec5a2b6d62268e254f12f1902e
+  data.tar.gz: e4168d9e617dbad8912a65dbe10be8a3a32a6a08b18fd84542a05fa9803aeaef
 SHA512:
-  metadata.gz: 5afb2bcf079a1024b02260e7e428cbb5dbb7661d4df86e093c7813879b0617aae35c63bf25c4fac8025542e5ed05c0cd199eb1046b8ce52555e5ca1717c9662a
-  data.tar.gz: e5cc44483d1cf6eff9c9fcbc0beef4b0c42b70c46ce0a9d50c26b4f4012604dd17200104036833e062bdb3921232c0938d58841c779c7a952bc0562e919b78a3
+  metadata.gz: a49c8992b247138d92232d00123dd73986be81040bb1356fc912f97905644bbb35a38af431a1d81475b9ce07c644ab8c2aab3370c3fabaf685c0f8a93a16bd70
+  data.tar.gz: 48ccea615a818989da2a01babb5c9d344a5a7c94fbe2eea47301a1437f29aa671134011a626f317c128bcaf1aaa912a21f056e30c8b133643123df129aa7a470

data/lib/hecks/adapters/driven/script_runner.adapter

@@ -0,0 +1,3 @@
+Hecks.adapter "ScriptRunner" do
+  port "Script"
+end

data/lib/hecks/adapters/driven/script_runner.rb

@@ -0,0 +1,93 @@
+require "digest"
+require "json"
+
+module Hecks
+  module Adapters
+    # The `Script` port's adapter for a `Change`: it runs the scripts registered with it, in this
+    # process. A script is a name, a `plan` that says what it would do without doing it, and an
+    # `apply` that does it.
+    #
+    # `examine` plans a change and answers the plan with a digest of it. `perform` plans again and
+    # carries the change out only when the plan still has the digest that was confirmed, so what
+    # runs is what the person saw. A script that cannot be found, or whose plan or apply raises,
+    # refuses the change with its message.
+    class ScriptRunner
+      # A script: what it would do, and doing it. Both take the arguments as a Hash of String keys.
+      Script = Struct.new(:plan, :apply, keyword_init: true)
+
+      # Why a change was refused: an unknown script, a plan that moved, or the script's own failure.
+      class Refused < StandardError; end
+
+      class << self
+        # @return [Hash{String => Script}] the scripts this process can run, by name
+        def scripts = @scripts ||= {}
+
+        # @param name [String] the name a change asks for
+        # @param plan [#call] takes the arguments, returns the text of what the script would do
+        # @param apply [#call] takes the arguments, does it, returns the text of what happened
+        # @return [Script] the registered script
+        def register(name, plan:, apply:) = scripts[name.to_s] = Script.new(plan: plan, apply: apply)
+
+        # Forgets every registered script.
+        #
+        # @return [Hash] the empty registry
+        def reset! = @scripts = {}
+      end
+
+      # Accepts the arguments every driven adapter is built with and keeps none of them.
+      #
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] unused
+      # @param root [String, nil] unused
+      def initialize(aggregate: nil, settings: {}, root: nil); end
+
+      # Plans the change.
+      #
+      # @param held [Hash] the record: `script` and `arguments`
+      # @return [Hash{Symbol => Hash}] `plan:` what the script would do, and `digest:` its
+      #   fingerprint
+      # @raise [Refused] when the script is unknown or its plan raises
+      def examine(**held)
+        name, args = request(held)
+        text = planned(name, args)
+        { plan: { value: text }, digest: { value: digest(name, args, text) } }
+      end
+
+      # Carries out a confirmed change if its plan has not moved.
+      #
+      # @param held [Hash] the record: `script`, `arguments` and `planned_digest`
+      # @return [Hash{Symbol => Hash}] `report:` what the script reported
+      # @raise [Refused] when the script is unknown, the plan has moved, or the script raises
+      def perform(**held)
+        name, args = request(held)
+        current = digest(name, args, planned(name, args))
+        raise Refused, "the plan moved since it was confirmed; plan it again" unless current == plain(held[:planned_digest])
+
+        { report: { value: run(name, :apply, args).to_s } }
+      end
+
+      private
+
+      def request(held) = [plain(held[:script]), arguments(held[:arguments])]
+
+      def planned(name, args) = run(name, :plan, args).to_s
+
+      def run(name, step, args)
+        script = self.class.scripts.fetch(name) { raise Refused, "no script is registered as #{name.inspect}" }
+        script.public_send(step).call(args)
+      rescue Refused
+        raise
+      rescue StandardError => e
+        raise Refused, "#{name} #{step} failed: #{e.message}"
+      end
+
+      # The digest stands for the script, its arguments and its plan, so none of them can change
+      # between confirming and applying.
+      def digest(name, args, text) = Digest::SHA256.hexdigest(JSON.generate([name, args.sort.to_h, text]))
+
+      def arguments(list) = Array(list).to_h { |pair| [plain(pair[:key]), plain(pair[:value])] }
+
+      def plain(cell) = cell.is_a?(Hash) && cell.key?(:value) ? cell[:value] : cell
+    end
+  end
+end

data/lib/hecks/adapters/driven.rb

@@ -27,3 +27,4 @@ require_relative "driven/governance_authorization"
 require_relative "driven/identity_registry"
 require_relative "driven/google_authentication"
 require_relative "driven/claude_code"
+require_relative "driven/script_runner"

data/lib/hecks/adapters/driving/cli_runner/resolution.rb

@@ -82,8 +82,9 @@ module Hecks
           # with the first sentence of what it is for.
           #
           # @return [Hash{Symbol => Object}] `:hide` and `:chapters` (pairs of word and summary)
-          def audience(runtime, launcher, maintainer: LauncherOptions.maintainer?)
-            shown = LauncherOptions.audience(launcher, maintainer)
+          def audience(runtime, launcher, maintainer: LauncherOptions.maintainer?,
+                       newcomer: !maintainer && Newcomer.applies?)
+            shown = (newcomer && Newcomer.audience(launcher)) || LauncherOptions.audience(launcher, maintainer)
             return shown unless shown[:chapters]
 
             shown.merge(chapters: chapter_summaries(runtime, shown[:chapters]))
@@ -102,7 +103,9 @@ module Hecks
 
           # Names who the help is for, so the help remembered for one is not given to the other.
           def audience_key
-            LauncherOptions.maintainer? ? "maintainer" : "project"
+            return "maintainer" if LauncherOptions.maintainer?
+
+            Newcomer.applies? ? "newcomer" : "project"
           end
 
           # Reads the entry words of a line: whether it asks a query, the bare name, and the words

data/lib/hecks/adapters/driving/cli_runner.rb

@@ -3,6 +3,7 @@ require_relative "cli"
 require_relative "command_request"
 require_relative "json"
 require_relative "launcher_options"
+require_relative "newcomer"
 require_relative "../../projector"
 require_relative "../../ports/clock"
 require_relative "cli_runner/answers"

data/lib/hecks/adapters/driving/newcomer.rb

@@ -0,0 +1,50 @@
+require_relative "launcher_options"
+
+module Hecks
+  module Adapters
+    module Driving
+      # The launcher's help for someone starting out: a folder with no bluebook in it has no use yet
+      # for the commands that act on a domain, so the help lists only the `newcomer` commands the
+      # chapter's `launcher` setting names (`hecks --all` lists the rest).
+      module Newcomer
+        # How deep under a directory a bluebook may sit and still make it a project:
+        # `Hecks.bluebook` beside it, or `bluebook/pizzas.bluebook` one folder down, as the
+        # examples keep theirs.
+        PROJECT_GLOBS = ["*.bluebook", "*/*.bluebook", "*/*/*.bluebook"].freeze
+
+        module_function
+
+        # Whether the person is in a folder with no bluebook in it, outside a hecks checkout.
+        #
+        # @param dir [String] where the command line was typed
+        # @param env [#[]] the environment
+        # @return [Boolean] true when no `.bluebook` stands in `dir` or up to two folders below it
+        def applies?(dir = Dir.pwd, env = ENV)
+          return false if LauncherOptions.maintainer?(dir, env)
+
+          PROJECT_GLOBS.none? { |pattern| bluebook_under?(dir, pattern) }
+        end
+
+        # The help options a newcomer gets: only the setting's `newcomer` commands, and no chapters.
+        #
+        # @param settings [Hash, nil] the chapter's `launcher` setting
+        # @return [Hash{Symbol => Object}, nil] `:only` and `:chapters`, or nil when the chapter
+        #   names no newcomer commands
+        def audience(settings)
+          return unless settings && settings[:newcomer]
+
+          { only: Array(settings[:newcomer]).map(&:to_s), chapters: [] }
+        end
+
+        # Whether `pattern` finds a bluebook under `dir`; a folder the person may not read holds
+        # none.
+        # @api private
+        def bluebook_under?(dir, pattern)
+          Dir.glob(File.join(File.expand_path(dir), pattern)).any?
+        rescue SystemCallError
+          false
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/assembly/contracts/read_models.rb

@@ -61,7 +61,7 @@ module Hecks
         "Member"    => Contract.new(
           holder: nil, make: nil,
           fields: {},
-          rows: { pairs: :pair_rows },
+          rows: { pairs: :member_pair_rows },
           derived: { position: :walk, pairs: [:folded, %i[members], nil] }
         )
       }.freeze

data/lib/hecks/bluebook/assembly/marks.rb

@@ -35,10 +35,10 @@ module Hecks
         # One identity part, as the String path `identity_paths` splits.
         def identity_path(part) = part[:value].to_s
 
-        # A member's fields, an open map, so the pairs arrive as a list.
-        # Values are unmarked because `ValueObject#to_h` spells them with `to_s`.
+        # A member's fields, an open map, so the pairs arrive as a list. Each value is already
+        # typed: `Reconstruction` reads a stored cell with `Scalars.unmark` before it gets here.
         def member(pairs)
-          pairs.to_h { |key, value| [key.to_sym, unmark_scalar(value)] }
+          pairs.to_h { |key, value| [key.to_sym, value] }
         end
 
         # A read model's gathered head; `as` is a Symbol because `ReadModel#to_h` spells it `to_s`.
@@ -49,18 +49,6 @@ module Hecks
         # Matches the builder's native `{field: :symbol}` shape.
         def group_by_field(row) = { field: row[:field].to_sym }
 
-        # Reads a member's scalar back from text. Unlike `read`, a bare word stays a
-        # String, because a closed set admits words far more often than symbols.
-        def unmark_scalar(value)
-          text = value.to_s
-          return true       if text == "true"
-          return false      if text == "false"
-          return text.to_i  if text.match?(/\A-?\d+\z/)
-          return text.to_f  if text.match?(/\A-?\d+\.\d+\z/)
-
-          text
-        end
-
         # A saga's argument bindings; Literal marks a Symbol with a leading colon.
         def bindings(with) = Array(with).to_h { |key, value| [key.to_sym, read(value)] }
 

data/lib/hecks/bluebook/assembly/scalars.rb

@@ -0,0 +1,39 @@
+module Hecks
+  module Bluebook
+    class Assembly
+      # How a `member` cell is spelled as stored text, and read back. The meta-domain holds a cell
+      # as text, so a quoted `"true"` and a bare `true` need different spellings: a boolean or
+      # number is its own spelling, and a String that would read back as one, or as quoted text,
+      # is quoted so it stays a String. The Rust parser reads a cell the same way (`cell_value`
+      # in `parse/value_object.rs`).
+      module Scalars
+        module_function
+
+        # @param value [Object] a cell as the builder holds it
+        # @return [Object] `value` itself unless it is a String that reads back as another type, in
+        #   which case its quoted spelling
+        def mark(value)
+          return value unless value.is_a?(String)
+
+          unmark(value) == value ? value : Literal.quote(value)
+        end
+
+        # Unlike `Literal.read`, a bare word stays a String, because a closed set admits words far
+        # more often than symbols; quoted text is a String whatever it spells.
+        #
+        # @param value [#to_s] a cell's stored text
+        # @return [Object] the String, boolean or number the text spells
+        def unmark(value)
+          text = value.to_s
+          return Literal.unquote(text) if Literal.quoted?(text)
+          return true       if text == "true"
+          return false      if text == "false"
+          return text.to_i  if text.match?(/\A-?\d+\z/)
+          return text.to_f  if text.match?(/\A-?\d+\.\d+\z/)
+
+          text
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/meta_validator/readings.rb

@@ -70,6 +70,12 @@ module Hecks
           Array(map&.to_h).map { |key, value| { key: key, value: value } }
         end
 
+        # A member's cells, each spelled so a quoted `"true"` stays a String and a bare `true` a
+        # boolean.
+        def member_pair_rows(map)
+          Array(map&.to_h).map { |key, value| { key: key, value: Assembly::Scalars.mark(value) } }
+        end
+
         # Flattens options via `extra_options_to_h` — a new option needs no
         # change here. `filters: true` reads wheres/order_by/limit live off
         # the node, not `to_h`, so wire-format changes there don't affect it.

data/lib/hecks/bluebook/meta_validator/reconstruction.rb

@@ -41,11 +41,14 @@ module Hecks
         # dispatched state, one member at a time, not behind a `DeclaredIn` query.
         def members_row(row) = members_of(row)
 
-        # The key is stringified, never the value: a pair's value keeps whatever
-        # native Ruby type the source line actually wrote.
+        # The key is stringified, never the value: a pair's value is read back from its text by
+        # `Assembly::Scalars`, so a quoted cell returns a String and `true`, `false` and numbers
+        # return as the builder holds them.
         def members_of(value_object_row)
           Array(value_object_row[:members]).map do |member|
-            Array(member[:pairs]).map { |pair| [text(pair[:key]).to_s, text(pair[:value])] }
+            Array(member[:pairs]).map do |pair|
+              [text(pair[:key]).to_s, Assembly::Scalars.unmark(text(pair[:value]))]
+            end
           end
         end
 

data/lib/hecks/bluebook/meta_validator/syntax_boot.rb

@@ -37,19 +37,23 @@ module Hecks
         end
 
         # Dispatches every seed row into a fresh "Bluebook" instance and
-        # reads the result back.
+        # reads the result back. The table is memoized for the process, so it is built with no
+        # ambient caller: an enclosing `Hecks.as_caller` would have the language's own
+        # `Language`-role commands refused.
         def boot
-          bluebook = MetaValidator.grammar_registry.bluebook("Bluebook")
-          # `fresh_runtime`, not a new `Runtime::Registry` — the grammar
-          # registry already has "Bluebook" registered and its adapter
-          # ports already loaded.
-          runtime = MetaValidator.fresh_runtime
-
-          declare_syntax(runtime, bluebook)
-          admit_keywords(runtime, bluebook)
-          admit_arguments(runtime, bluebook)
-
-          read_back(runtime, bluebook)
+          Runtime::Caller.without do
+            bluebook = MetaValidator.grammar_registry.bluebook("Bluebook")
+            # `fresh_runtime`, not a new `Runtime::Registry` — the grammar
+            # registry already has "Bluebook" registered and its adapter
+            # ports already loaded.
+            runtime = MetaValidator.fresh_runtime
+
+            declare_syntax(runtime, bluebook)
+            admit_keywords(runtime, bluebook)
+            admit_arguments(runtime, bluebook)
+
+            read_back(runtime, bluebook)
+          end
         end
 
         # An Integer stays an Integer — `position` is `Position`-typed, so

data/lib/hecks/bluebook/meta_validator.rb

@@ -168,32 +168,39 @@ module Hecks
       end
 
       # The booted, self-judged language registry every ordinary bluebook is
-      # judged against — built once per process and memoized, with shadow parsing off: a caller
-      # inside `while_shadow_parsing` that is first to ask would otherwise memoize a grammar
-      # parsed in that mode, or fail to load it.
+      # judged against — built once per process and memoized, with shadow parsing off and no
+      # ambient caller bound. A caller inside `while_shadow_parsing` that is first to ask would
+      # otherwise memoize a grammar parsed in that mode, or fail to load it; one inside
+      # `Hecks.as_caller` would have the language's own `Language`-role commands refused, and the
+      # grammar would be memoized without the chapters those refusals dropped.
       #
       # @return [Runtime::Registry] the booted, fixpoint-judged language
       #   registry
       def self.grammar_registry
-        @grammar_registry ||= while_not_shadow_parsing do
-          registry = load_grammar_into(Runtime::Registry.new)
-          # Assigned before the fixpoint judge below, since judging re-enters
-          # grammar_registry (via fresh_runtime/Plan.for) and a bare `||=`
-          # would still be nil mid-evaluation, recursing forever.
-          @grammar_registry = registry
-          # The language now judges itself; every bluebook from here on is
-          # judged by that assembled graph, not the raw bootstrap one. Must
-          # run after load_grammar_into's ensure clears @bootstrapping.
-          while_forcing_fixpoint do
-            LANGUAGE_CHAPTERS.each { |name| registry.add_bluebook(call(registry.bluebook(name))) }
-            load_attached_grammar_into(registry)
-          end
-          # Keyed on this registry's object identity, not a bare boolean, so
-          # a manual reset can never leave a stale "ready" from the previous
-          # cycle.
-          @grammar_ready_for = registry.object_id
-          registry
+        @grammar_registry ||= while_not_shadow_parsing { Runtime::Caller.without { build_grammar_registry } }
+      end
+
+      # The one-time build behind `grammar_registry`.
+      #
+      # @return [Runtime::Registry] the booted, fixpoint-judged language registry
+      def self.build_grammar_registry
+        registry = load_grammar_into(Runtime::Registry.new)
+        # Assigned before the fixpoint judge below, since judging re-enters
+        # grammar_registry (via fresh_runtime/Plan.for) and a bare `||=`
+        # would still be nil mid-evaluation, recursing forever.
+        @grammar_registry = registry
+        # The language now judges itself; every bluebook from here on is
+        # judged by that assembled graph, not the raw bootstrap one. Must
+        # run after load_grammar_into's ensure clears @bootstrapping.
+        while_forcing_fixpoint do
+          LANGUAGE_CHAPTERS.each { |name| registry.add_bluebook(call(registry.bluebook(name))) }
+          load_attached_grammar_into(registry)
         end
+        # Keyed on this registry's object identity, not a bare boolean, so
+        # a manual reset can never leave a stale "ready" from the previous
+        # cycle.
+        @grammar_ready_for = registry.object_id
+        registry
       end
 
       # Whether `grammar_registry`'s memoized singleton has finished its

data/lib/hecks/bluebook.rb

@@ -35,6 +35,7 @@ require_relative "bluebook/assembly/contract"
 require_relative "bluebook/assembly/contracts"
 require_relative "bluebook/assembly/specializer"
 require_relative "bluebook/assembly/build"
+require_relative "bluebook/assembly/scalars"
 require_relative "bluebook/assembly/marks"
 require_relative "bluebook/assembly/aggregate_assembly"
 require_relative "bluebook/assembly"

data/lib/hecks/deploy/bluebook/deploy.bluebook

@@ -212,6 +212,7 @@ Hecks.bluebook "Deploy" do
     attribute :volume_gb,      VolumeGb
     attribute :database_class, DatabaseClass
     attribute :storage_gb,     StorageGb
+    attribute :cdn_aliases,    list_of(CdnAlias), optional: true
 
     value_object "DomainName" do
       attribute :value, String
@@ -251,8 +252,19 @@ Hecks.bluebook "Deploy" do
       invariant("storage is at most 65536 GB") { value <= 65536 }
     end
 
-    # All six required for the same reason as `FargateTarget.Declare`; this validates a target
-    # already resolved by `hecks deploy project`'s defaults.
+    # A host name the CloudFront edge answers on, such as app.example.com. Lowercase labels only:
+    # CloudFront refuses a name its certificate does not cover at deploy, which this cannot see.
+    value_object "CdnAlias" do
+      attribute :value, String
+      invariant("a CDN alias is a lowercase host name such as app.example.com") do
+        value.to_s.match?(/\A([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z][a-z0-9-]{0,61}[a-z0-9]\z/)
+      end
+      invariant("a CDN alias is at most 253 characters") { value.to_s.length <= 253 }
+    end
+
+    # The first six are required for the same reason as `FargateTarget.Declare`; this validates a
+    # target already resolved by `hecks deploy project`'s defaults. `cdn_aliases` is the one
+    # optional setting: naming at least one asks for the CloudFront edge stack.
     command "Declare" do
       goal "Validate one domain's AwsBox deploy target before anything is generated from it"
 
@@ -262,6 +274,7 @@ Hecks.bluebook "Deploy" do
       attribute :volume_gb,      VolumeGb
       attribute :database_class, DatabaseClass
       attribute :storage_gb,     StorageGb
+      attribute :cdn_aliases,    list_of(CdnAlias), optional: true
 
       sets :domain
       sets :region
@@ -269,6 +282,7 @@ Hecks.bluebook "Deploy" do
       sets :volume_gb
       sets :database_class
       sets :storage_gb
+      sets :cdn_aliases
 
       emits "BoxTargetDeclared"
     end
@@ -2792,7 +2806,7 @@ Hecks.bluebook "Deploy" do
     end
 
     command "ProjectOidc" do
-      goal "Write each domain's OIDC client and scope manifest beside it as oidc.json"
+      goal "Write each domain's OIDC client and scope manifest beside it: oidc.json, or one <chapter>.oidc.json for each chapter of a directory that holds several"
 
       attribute :domains, DomainList, optional: true
       attribute :run,     RunKey

data/lib/hecks/framework/bluebook/change.behaviors

@@ -0,0 +1,30 @@
+Hecks.behaviors "Change" do
+  vision "A change names its script, faults when that script cannot plan it, and is confirmed only from a plan."
+
+  loads "change.bluebook", "governance.bluebook", "change.hecksagon", "../../../../spec/fixtures/change/governance.hecksagon"
+
+  test "Request refuses a change that names no script" do
+    tests "Request", on: "Change"
+    input run: { value: "c1" }, script: { value: "" }
+    expect refused: "must match"
+  end
+
+  test "Request refuses a change that is not named" do
+    tests "Request", on: "Change"
+    input run: { value: "" }, script: { value: "rename" }
+    expect refused: "must match"
+  end
+
+  test "Request faults a change whose script nobody registered" do
+    tests "Request", on: "Change"
+    input run: { value: "c2" }, script: { value: "no_such_script" }
+    expect status: "faulted"
+  end
+
+  test "Confirm refuses a change that was never planned" do
+    tests "Confirm", on: "Change"
+    setup  "Change::Change.Request", run: { value: "c3" }, script: { value: "no_such_script" }
+    input  run: { value: "c3" }, digest: { value: "ab12" }
+    expect refused: "the digest confirmed is the digest planned"
+  end
+end