hecks 3.10.0 → 3.11.0

data/lib/hecks/projections/site/cms_editor/pickers.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require_relative "targets"
+
+module Hecks
+  module Projections
+    module Site
+      module CmsEditor
+        # Which attributes name another aggregate's instance, found by the bluebook's own
+        # declarations, so the editor offers the instances in place of a text box. In this order:
+        # a `<kind>:<slug>` key by its pattern (see `KeyKinds`), each kind that is an aggregate's
+        # snake-case name offering that aggregate; a `reference_to` attribute whose target is an
+        # editor aggregate; a value object of one text part named `<Stem>Ref`, where `<Stem>` is
+        # the type of an editor aggregate's identity or its name; and `<Image|Picture|Photo|Media>
+        # Ref` with a picture aggregate, which suggests pictures and accepts any other text. A
+        # target is found once: the same chapter's, else the only one of its name; else none.
+        module Pickers
+          # The stems that name a picture, for the editor's picture aggregate.
+          PICTURE_STEMS = %w[Image Picture Photo Media].freeze
+
+          module_function
+
+          # @param aggregates [Array<Hash{String => Object}>] the aggregates as `Schema` shapes them
+          # @param media [Hash{String => Object}, nil] the picture aggregate, as `Media` says
+          # @return [Array<Hash{String => Object}>] the aggregates, each attribute that names an
+          #   instance carrying its `picker`
+          def apply(aggregates, media = nil)
+            targets = Targets.new(aggregates, media)
+            aggregates.map { |agg| annotate(agg, targets) }
+          end
+
+          # @return [Hash{String => Object}] `agg` with a picker on each attribute that has one
+          def annotate(agg, targets)
+            mark = ->(list) { list.map { |attr| with_picker(attr, agg, targets) } }
+            agg.merge("attributes" => mark.call(agg["attributes"]), "valueObjects" => objects(agg, mark),
+                      "commands" => marked(agg["commands"], mark), "queries" => marked(agg["queries"], mark))
+          end
+
+          # @return [Array<Hash>] the commands or queries, the attributes of each marked
+          def marked(items, mark) = items.map { |item| item.merge("attributes" => mark.call(item["attributes"])) }
+
+          # @return [Hash{String => Array}] the value objects, the parts of one of several parts
+          #   marked; a value object of one part is entered as the attribute that names it
+          def objects(agg, mark)
+            agg["valueObjects"].transform_values do |parts|
+              parts.size == 1 ? parts.map { |part| part.except("keys") } : mark.call(parts)
+            end
+          end
+
+          # @return [Hash{String => Object}] `attr` with its `picker`, or as it was
+          def with_picker(attr, agg, targets)
+            picker = picker_for(attr, agg, targets)
+            picker ? attr.except("keys").merge("picker" => picker) : attr
+          end
+
+          def picker_for(attr, agg, targets)
+            return kinds(attr["keys"], agg, targets) if attr["keys"]
+            return targets.named(attr["target"], agg) if attr["kind"] == "reference"
+
+            stem = reference_stem(attr, agg)
+            stem && (targets.keyed_by(stem, agg) || (targets.pictures if PICTURE_STEMS.include?(stem)))
+          end
+
+          # @return [Hash{String => Array}] one entry per kind, with the aggregate it names if any
+          def kinds(words, agg, targets)
+            { "kinds" => words.map { |word| { "kind" => word, **(targets.kind(word, agg) || {}) } } }
+          end
+
+          # @return [String, nil] `Stem` of a `StemRef` value object that has one plain text part
+          def reference_stem(attr, agg)
+            return nil unless plain_text_object?(attr, agg["valueObjects"][attr["type"]])
+
+            stem = attr["type"].delete_suffix("Ref")
+            stem unless stem.empty? || stem == attr["type"]
+          end
+
+          # @return [Boolean] whether `attr` is a value object whose one part is a single text
+          def plain_text_object?(attr, parts)
+            attr["kind"] == "object" && parts&.size == 1 && parts.first["kind"] == "text" && !parts.first["list"]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/cms_editor/preview.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Hecks
+  module Projections
+    module Site
+      module CmsEditor
+        # The `Editor` row's `preview`: where a record is shown on the site, as a URL template the
+        # editor frames in a side drawer.
+        #
+        # A template is an `http://` or `https://` address, or a path that starts with one slash,
+        # with the placeholders `{key}`, `{kind}`, `{slug}` and `{id}` filled from a record's
+        # identity when the page is built. Anything else is refused, so a template cannot name a
+        # scheme that runs script (`javascript:`), a host written with credentials, or a
+        # placeholder the editor would leave unfilled. A placeholder may not stand in the origin
+        # (scheme, host and port), because the content security policy names that origin once, at
+        # build time, and allows no other frame.
+        module Preview
+          # The words a template may put in braces.
+          PLACEHOLDERS = %w[key kind slug id].freeze
+
+          # An absolute address: the origin, then whatever follows it.
+          ABSOLUTE = %r{\A(?<origin>https?://[^/?#\s]+)(?<rest>.*)\z}m
+
+          module_function
+
+          # @param template [String] the row's `preview`, which may be empty
+          # @return [Array<String>] every reason the template is refused; empty when it is usable
+          def problems(template)
+            return [] if template.empty?
+
+            found = []
+            found << "must not hold whitespace" if template.match?(/\s/)
+            found.concat(shape_problems(template))
+            found.concat(placeholder_problems(template))
+            found.map { |problem| "preview #{template.inspect} #{problem}" }
+          end
+
+          # @return [String, nil] what the content security policy's `frame-src` names for the
+          #   template: its origin, `'self'` for a path, or nil for no preview
+          def frame_source(template)
+            return nil if template.empty?
+
+            found = ABSOLUTE.match(template)
+            found ? found[:origin] : "'self'"
+          end
+
+          # @return [Array<String>] the problems with the scheme, the host and the path
+          def shape_problems(template)
+            found = ABSOLUTE.match(template)
+            return path_problems(template) unless found
+
+            origin_problems(found[:origin])
+          end
+
+          # @return [Array<String>] the problems with a path template
+          def path_problems(template)
+            return ["must be an http(s) address or a path that starts with one slash"] unless template.start_with?("/")
+            return ["must not start with two slashes, which names another host"] if template.start_with?("//")
+
+            []
+          end
+
+          # @return [Array<String>] the problems with the origin of an absolute template
+          def origin_problems(origin)
+            found = []
+            found << "must not name credentials in the address" if origin.include?("@")
+            found << "must not hold a placeholder in the scheme, host or port" if origin.include?("{")
+            found << "names no host" if !origin.include?("{") && URI.parse(origin).host.to_s.empty?
+            found
+          rescue URI::InvalidURIError
+            ["is not a valid address"]
+          end
+
+          # @return [Array<String>] a problem for each unknown placeholder and each stray brace
+          def placeholder_problems(template)
+            unknown = template.scan(/\{([^{}]*)\}/).flatten.uniq - PLACEHOLDERS
+            found = unknown.map do |name|
+              "names the placeholder {#{name}}; the placeholders are #{PLACEHOLDERS.map do |word|
+                "{#{word}}"
+              end.join(", ")}"
+            end
+            found << "has a brace that is not part of a placeholder" if template.gsub(/\{[^{}]*\}/, "").match?(/[{}]/)
+            found
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/cms_editor/relations.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Projections
+    module Site
+      module CmsEditor
+        # The records that belong to one record, found by the keys they carry. Aggregate `B` is
+        # related to `A` when `B`'s identity is a `<kind>:<slug>` key (see `KeyKinds`) whose
+        # kinds include `A`'s snake-case name, so `post:first-light` keys the `B` of the `Post`
+        # `first-light`.
+        #
+        # The rule reads the declared pattern and what the kind resolves to (see `Pickers`),
+        # never a name. A `B` is shown by its shape: a **document** (a rich-text body), a
+        # **gallery** (a list that names pictures) or **metadata** (anything else). Its creating
+        # command is the first that takes the identity; its editing command is the draft-saving
+        # command of a document that keeps drafts (see `Drafts`), else the first command on an
+        # existing record that is neither a lifecycle move nor destructive and takes the body or
+        # the pictures.
+        module Relations
+          module_function
+
+          # @param aggregates [Array<Hash{String => Object}>] the aggregates as `Pickers` leaves
+          #   them
+          # @param media [Hash{String => Object}, nil] the picture aggregate, as `Media` says
+          # @return [Array<Hash{String => Object}>] each aggregate, carrying `related` when other
+          #   aggregates are keyed by it
+          def apply(aggregates, media = nil)
+            aggregates.map do |agg|
+              found = aggregates.reject { |other| other.equal?(agg) }.filter_map { |other| relation(other, agg, media) }
+              found.empty? ? agg : agg.merge("related" => found)
+            end
+          end
+
+          # @return [Hash{String => Object}, nil] how `other` is related to `agg`, or nil when it
+          #   is not
+          def relation(other, agg, media)
+            key = other["attributes"].find { |attr| attr["name"] == other["identity"] }
+            return nil unless key && keyed_by?(key, agg)
+
+            shape, field = shape_of(other, media)
+            { "aggregate" => other["name"], "chapter" => other["chapter"], "field" => key["name"], "shape" => shape,
+              "create" => creating(other, key), "edit" => editing(other, field) }.compact
+          end
+
+          # @return [Boolean] whether `key` is declared a key of `<agg's snake name>:<slug>`
+          def keyed_by?(key, agg)
+            (key.dig("picker", "kinds") || []).any? { |kind| kind["target"] == agg["name"] && kind["chapter"] == agg["chapter"] }
+          end
+
+          # @return [Array(String, String)] the shape, and the attribute that gives it
+          def shape_of(other, media)
+            body = other["attributes"].find { |attr| attr["widget"] == "body" && !attr["list"] }
+            return ["document", body["name"]] if body
+
+            pictures = pictures_of(other, media)
+            pictures ? ["gallery", pictures["name"]] : ["metadata", nil]
+          end
+
+          # @return [Hash{String => Object}, nil] the list attribute that names pictures
+          def pictures_of(other, media)
+            return nil unless media
+
+            other["attributes"].find { |attr| attr["list"] && attr.dig("picker", "target") == media["aggregate"] }
+          end
+
+          # @return [String, nil] the first creating command that takes the identity
+          def creating(other, key)
+            other["commands"].find do |command|
+              command["creates"] && command["attributes"].any? do |attr|
+                attr["name"] == key["name"]
+              end
+            end&.fetch("name")
+          end
+
+          # @return [String, nil] the command that changes the record's body, pictures or fields
+          def editing(other, field)
+            return other.dig("drafts", "save") if other["drafts"] && field == other.dig("drafts", "live")
+
+            moves = (other.dig("lifecycle", "transitions") || []).map { |move| move["verb"] }
+            other["commands"].find { |command| edits?(command, field, moves) }&.fetch("name")
+          end
+
+          def edits?(command, field, moves)
+            names = command["attributes"].map { |attr| attr["name"] }
+            !command["creates"] && !command["destructive"] && !moves.include?(command["name"]) &&
+              !names.empty? && (field.nil? || names.include?(field))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/cms_editor/scale_checks.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Projections
+    module Site
+      module CmsEditor
+        # What the `Editor` row's settings for many chapters and long lists must satisfy: chapters
+        # named once each, roles given for a chapter the editor edits, and a page size a list can
+        # hold. A chapter's name is part of an address, so it cannot be spelled as one of the
+        # editor's own paths.
+        module ScaleChecks
+          # The most instances a list may show to a page.
+          MAX_PAGE = 1000
+
+          # The first segments of the editor's own addresses, which no chapter may be named.
+          RESERVED = %w[assets media logout api scheduled].freeze
+
+          module_function
+
+          # @param row [Hash{Symbol => String}] the row, defaults filled
+          # @return [Array<String>] every problem with `chapter`, `chapter_roles` and `page_size`
+          def problems(row)
+            chapters = row[:chapter].split(",").map(&:strip)
+            [*chapter_problems(chapters), *role_problems(row[:chapter_roles], chapters), *page_size_problems(row[:page_size])]
+          end
+
+          # @return [Array<String>] the problems with an empty, repeated or reserved chapter name
+          def chapter_problems(chapters)
+            found = []
+            found << "chapter names no chapter" if chapters.reject(&:empty?).empty?
+            repeated = chapters.find { |name| chapters.count(name) > 1 }
+            found << "chapter names #{repeated.inspect} twice" if repeated
+            [*found, *reserved_problems(chapters)]
+          end
+
+          # @return [Array<String>] a problem for each chapter spelled as an address of the editor's
+          def reserved_problems(chapters)
+            return [] if chapters.size < 2
+
+            (chapters & RESERVED).map do |name|
+              "chapter #{name.inspect} is the first part of an address the editor serves; name it another way"
+            end
+          end
+
+          # @return [Array<String>] the problems with `Chapter=Role,Role;Chapter=Role` entries
+          def role_problems(text, chapters)
+            text.split(";").map(&:strip).reject(&:empty?).flat_map do |entry|
+              name, roles = entry.split("=", 2)
+              next ["chapter_roles #{entry.inspect} must read Chapter=Role,Role"] if roles.to_s.strip.empty?
+              next [] if chapters.include?(name.strip)
+
+              ["chapter_roles names #{name.strip.inspect}, which is not a chapter of this editor"]
+            end
+          end
+
+          # @return [Array<String>] the problem with a page size that is not a whole 1 to 1000
+          def page_size_problems(size)
+            return [] if size.match?(/\A[1-9]\d{0,3}\z/) && size.to_i <= MAX_PAGE
+
+            ["page_size #{size.inspect} must be a whole number from 1 to #{MAX_PAGE}"]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/cms_editor/scheduling.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Projections
+    module Site
+      module CmsEditor
+        # An aggregate whose records are actions to run later, found by shape. The editor makes
+        # and changes the records and never runs an action: a runner elsewhere does.
+        #
+        # It has a **subject** (a plain `<kind>:<slug>` key, see `KeyKinds`), an **action** from
+        # a closed set (`one_of`), a **due time** that is a moment (see `Moment`), a
+        # **lifecycle** whose first state moves to at least two states that move nowhere, and a
+        # **creating command** that takes the three. The command that reschedules takes the due
+        # time; the one that cancels is a destructive move from the first state to a final one;
+        # the reason is the first optional plain text left over; the query takes the subject
+        # alone. The first such aggregate is the one.
+        module Scheduling
+          # What a scheduling aggregate's attributes are called in its record: `subject`,
+          # `action`, `due`.
+          ROLES = %w[subject action due].freeze
+
+          # The widgets of an integer that is a moment.
+          MOMENTS = %w[date datetime].freeze
+
+          module_function
+
+          # @param aggregates [Array<Hash{String => Object}>] the aggregates as `Pickers` leaves
+          #   them
+          # @return [Hash{String => Object}, nil] the scheduling aggregate and its parts; nil when
+          #   none
+          def read(aggregates)
+            aggregates.lazy.filter_map { |agg| shape(agg) }.first
+          end
+
+          # @return [Hash{String => Object}, nil] `agg` as the scheduling aggregate, or nil
+          def shape(agg)
+            parts = parts_of(agg)
+            schedule = parts && endings(agg["lifecycle"]).size > 1 && creating(agg, parts)
+            return nil unless schedule
+
+            { "aggregate" => agg["name"], "chapter" => agg["chapter"], **parts, "pending" => agg.dig("lifecycle", "default"),
+              "schedule" => schedule["name"], **optional(agg, parts, schedule) }.compact
+          end
+
+          # @return [Hash{String => Object}, nil] the subject, action, actions and due time, or nil
+          def parts_of(agg)
+            return nil unless agg["lifecycle"]
+
+            plain = agg["attributes"].reject { |attr| attr["list"] }
+            found = [subject_of(agg, plain), plain.find { |attr| attr["options"] }, plain.find { |attr| moment?(attr) }]
+            describe(*found) if found.all?
+          end
+
+          # @return [Boolean] whether the attribute is an integer that is a moment
+          def moment?(attr) = MOMENTS.include?(attr["widget"])
+
+          # @return [Hash{String => Object}] the three attributes' names, and the action's members
+          def describe(subject, action, due)
+            { "subject" => subject["name"], "action" => action["name"], "actions" => action["options"], "due" => due["name"] }
+          end
+
+          # @return [Hash{String => Object}, nil] the attribute that is a key of a kind, the
+          #   identity last
+          def subject_of(agg, plain)
+            plain.select { |attr| attr.dig("picker", "kinds") }.min_by { |attr| attr["name"] == agg["identity"] ? 1 : 0 }
+          end
+
+          # @return [Array<String>] the final states the first state moves to: states nothing
+          #   moves out of
+          def endings(lifecycle)
+            moves = lifecycle["transitions"]
+            first = moves.select { |move| move["from"].include?(lifecycle["default"]) }.map { |move| move["to"] }.uniq
+            first - moves.flat_map { |move| move["from"] }
+          end
+
+          # @return [Hash{String => Object}, nil] the creating command that takes the subject,
+          #   action and due time
+          def creating(agg, parts)
+            agg["commands"].find { |cmd| cmd["creates"] && takes?(cmd, parts.values_at(*ROLES)) }
+          end
+
+          # @return [Boolean] whether the command takes every one of the named attributes
+          def takes?(cmd, names) = (names - cmd["attributes"].map { |attr| attr["name"] }).empty?
+
+          # @return [Hash{String => Object}] the commands, query and reason that may be missing
+          def optional(agg, parts, schedule)
+            { "reschedule" => rescheduling(agg, parts), "cancel" => cancelling(agg), "query" => querying(agg, parts),
+              "reason" => reason(agg, parts), "generated" => generated?(agg, parts, schedule) }
+          end
+
+          # @return [String, nil] the command on a record, not a lifecycle move, that takes the
+          #   due time
+          def rescheduling(agg, parts)
+            agg["commands"].find { |cmd| !cmd["creates"] && !move?(agg, cmd) && takes?(cmd, [parts["due"]]) }&.fetch("name")
+          end
+
+          # @return [String, nil] the destructive lifecycle move from the first state to a final
+          #   one
+          def cancelling(agg)
+            agg["commands"].find { |cmd| cmd["destructive"] && ends?(agg, cmd) }&.fetch("name")
+          end
+
+          # @return [String, nil] the query whose one argument is the subject
+          def querying(agg, parts)
+            agg["queries"].find { |query| query["attributes"].map { |attr| attr["name"] } == [parts["subject"]] }&.fetch("name")
+          end
+
+          # @return [Boolean] whether the command is a lifecycle move
+          def move?(agg, cmd) = agg["lifecycle"]["transitions"].any? { |move| move["verb"] == cmd["name"] }
+
+          # @return [Boolean] whether the command moves a first-state record to a final state
+          def ends?(agg, cmd)
+            lifecycle = agg["lifecycle"]
+            final = endings(lifecycle)
+            lifecycle["transitions"].any? do |move|
+              move["verb"] == cmd["name"] && move["from"].include?(lifecycle["default"]) && final.include?(move["to"])
+            end
+          end
+
+          # @return [String, nil] the first optional plain text attribute no other part uses
+          def reason(agg, parts)
+            used = [agg["identity"], *parts.values_at(*ROLES)]
+            spare = agg["attributes"].find { |attr| attr["optional"] && !used.include?(attr["name"]) && plain_text?(agg, attr) }
+            spare&.fetch("name")
+          end
+
+          # @return [Boolean] whether the attribute is one plain text, alone or as a value
+          #   object's only part
+          def plain_text?(agg, attr)
+            return false if %w[list picker options widget].any? { |key| attr[key] }
+
+            parts = agg["valueObjects"][attr["type"]]
+            parts ? lone_text?(parts) : attr["kind"] == "text"
+          end
+
+          # @return [Boolean] whether the parts are one plain text
+          def lone_text?(parts) = parts.size == 1 && parts.first["kind"] == "text" && !parts.first["list"]
+
+          # @return [true, nil] whether the creating command takes an identity that is not the
+          #   subject,
+          #   which the editor then makes itself
+          def generated?(agg, parts, schedule)
+            taken = schedule["attributes"].any? { |attr| attr["name"] == agg["identity"] }
+            true if taken && agg["identity"] != parts["subject"]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/cms_editor/schema.rb

@@ -1,7 +1,16 @@
 # frozen_string_literal: true
 
 require_relative "attributes"
+require_relative "blocks"
+require_relative "clearing"
+require_relative "composition"
+require_relative "destructive"
+require_relative "drafts"
+require_relative "limits"
 require_relative "media"
+require_relative "pickers"
+require_relative "relations"
+require_relative "scheduling"
 
 module Hecks
   module Projections
@@ -18,17 +27,55 @@ module Hecks
         # A query that `returns` a value object is answered outside the domain and is left out: the
         # host refuses it, so a list cannot be built from it.
         class Schema
-          # @param chapter [Bluebook::Chapter] the domain's chapter
-          # @param skip [Array<String>] aggregates to leave out
-          # @return [Hash{String => Object}] the domain's name and its aggregates
-          # @raise [ArgumentError] when no aggregate is left
-          def self.read(chapter, skip: [])
-            aggregates = chapter.aggregates.reject { |agg| skip.include?(agg.hecks_name) }
-            raise ArgumentError, "the #{chapter.name} chapter has no aggregate to edit" if aggregates.empty?
-
-            shaped = aggregates.map { |agg| new(agg).to_h }
-            media = Media.read(shaped)
-            { "domain" => chapter.name, "aggregates" => shaped, **(media ? { "media" => media } : {}) }
+          # @param chapters [Bluebook::Chapter, Array<Bluebook::Chapter>] the chapter, or the
+          #   chapters in the order the row names them; the first names the domain addressed
+          # @param skip [Array<String>] aggregates to leave out: `Name`, or `Chapter::Name`
+          # @param pictures [Bluebook::Chapter, nil] another chapter whose picture aggregate the
+          #   editor's pictures use, in place of any in `chapters`
+          # @param roles [Hash{String => Array<String>}] the roles each chapter is limited to
+          # @return [Hash{String => Object}] the domain's name and its aggregates; `chapters` too
+          #   when there are several
+          # @raise [ArgumentError] when no aggregate is left, or `pictures` has no picture aggregate
+          def self.read(chapters, skip: [], pictures: nil, roles: {})
+            list = chapters.is_a?(Array) ? chapters : [chapters]
+            shaped = Composition.aggregates(list, skip: skip, roles: roles) { |agg| new(agg).to_h }
+            raise ArgumentError, "the #{list.map(&:name).join(", ")} chapter has no aggregate to edit" if shaped.empty?
+
+            media = pictures ? elsewhere(pictures) : within(shaped, list.first.name)
+            assemble(list, Relations.apply(Pickers.apply(shaped, media), media), media)
+          end
+
+          # @return [Hash{String => Object}] the schema: the domain, the chapters when several, the
+          #   aggregates, and the picture and scheduling aggregates when there are such
+          def self.assemble(list, aggregates, media)
+            chapters = list.size > 1 ? { "chapters" => list.map(&:name) } : {}
+            scheduling = Scheduling.read(aggregates)
+            { "domain" => list.first.name, **chapters, "aggregates" => aggregates, **(media ? { "media" => media } : {}),
+              **(scheduling ? { "scheduling" => scheduling } : {}) }
+          end
+
+          # The picture aggregate among the editor's own, with the chapter that holds it when that
+          # is not the first, since the host is addressed by chapter.
+          #
+          # @return [Hash{String => Object}, nil] the picture aggregate, as `Media` describes it
+          def self.within(shaped, first)
+            found = Media.read(shaped)
+            chapter = found&.delete("chapter")
+            chapter && chapter != first ? found.merge("domain" => chapter) : found
+          end
+
+          # The picture aggregate of another chapter: the same record as one in the editor's own
+          # chapter, with the chapter's name and the aggregate itself, since the editor's own
+          # aggregates do not hold it.
+          #
+          # @return [Hash{String => Object}] the picture aggregate, as `Media` describes it
+          # @raise [ArgumentError] when the chapter has no aggregate that registers pictures
+          def self.elsewhere(chapter)
+            shaped = chapter.aggregates.map { |agg| new(agg).to_h }
+            found = Media.read(shaped)
+            raise ArgumentError, "the #{chapter.name} chapter has no aggregate that registers pictures" unless found
+
+            found.merge("domain" => chapter.name, "definition" => shaped.find { |agg| agg["name"] == found["aggregate"] })
           end
 
           # @param aggregate [Bluebook::Aggregate] one aggregate of the chapter
@@ -39,28 +86,51 @@ module Hecks
 
           # @return [Hash{String => Object}] the aggregate as the editor reads it
           def to_h
+            held = aggregate_attributes
+            drafts = Drafts.of(@agg, held)
             { "name" => @agg.hecks_name, "description" => @agg.description, "identity" => @agg.identified_by.to_s,
-              "lifecycle" => lifecycle, "attributes" => attributes(@agg.attributes.reject { |a| a.name == lifecycle_field }),
-              "valueObjects" => value_objects, "commands" => @agg.commands.map { |command| command(command) },
-              "queries" => queries }
+              "lifecycle" => lifecycle, "attributes" => held, "valueObjects" => value_objects,
+              "commands" => @agg.commands.map { |command| command(command) }, "queries" => queries,
+              **(drafts ? { "drafts" => drafts } : {}) }
           end
 
           private
 
           def lifecycle_field = @agg.lifecycle&.field
 
-          def attributes(list) = list.map { |attribute| @attributes.of(attribute) }
+          # The aggregate's own attributes, bounded by the aggregate's invariants (see `Limits`).
+          def aggregate_attributes
+            bounded(attributes(@agg.attributes.reject { |a| a.name == lifecycle_field }), @agg.invariants)
+          end
+
+          def attributes(list) = list.map { |attribute| limited(@attributes.of(attribute)) }
+
+          # `list` with what the holder's rules say about the most each may hold (see `Limits`).
+          def bounded(list, rules) = Limits.apply(list, rules)
+
+          # `attr` with the most its block list may hold, when a command's `given` says.
+          def limited(attr)
+            most = attr.key?("blockList") ? Blocks.maximum(@agg.commands, attr["name"]) : nil
+            most ? attr.merge("max" => most) : attr
+          end
 
           def value_objects
-            @agg.value_objects.to_h { |object| [object.hecks_name, attributes(object.attributes)] }
+            @agg.value_objects.to_h do |object|
+              [object.hecks_name, bounded(attributes(object.attributes), object.invariants)]
+            end
           end
 
           def lifecycle
+            @lifecycle ||= shaped_lifecycle
+          end
+
+          def shaped_lifecycle
             lifecycle = @agg.lifecycle
             return nil unless lifecycle
 
-            { "field" => lifecycle.field.to_s, "default" => lifecycle.default,
-              "transitions" => lifecycle.transitions.map { |verb, move| transition(verb, move) } }
+            shaped = { "field" => lifecycle.field.to_s, "default" => lifecycle.default,
+                       "transitions" => lifecycle.transitions.map { |verb, move| transition(verb, move) } }
+            shaped.merge("tones" => Destructive.tones(shaped))
           end
 
           def transition(verb, move)
@@ -69,9 +139,16 @@ module Hecks
 
           def command(command)
             { "name" => command.hecks_name, "goal" => command.goal, "role" => command.role, "creates" => command.creates?,
-              "on" => command.creates? ? nil : command.references.to_s, "attributes" => attributes(command.attributes) }
+              "on" => command.creates? ? nil : command.references.to_s,
+              "destructive" => Destructive.command?(command.hecks_name, lifecycle),
+              "attributes" => bounded(attributes(command.attributes), command.givens) }
+              .then { |shaped| clearing(shaped, command) }
           end
 
+          # Leaves the arguments that only clear (see `Clearing`) out of the command's form, and
+          # names those that are lists as `empty`, for the editor to send as empty lists.
+          def clearing(shaped, command) = Clearing.apply(shaped, Clearing.of(command, @agg))
+
           def queries
             @agg.queries.reject(&:returns).map do |query|
               { "name" => query.name, "description" => query.description, "attributes" => attributes(query.attributes) }