ecoportal-api-graphql 2.2.0 → 3.0.0

data/lib/ecoportal/api/graphql/model/template/instance.rb

@@ -0,0 +1,202 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Model
+        module Template
+          # The mutable, in-memory template: `Model::Template.load(client, id:)` returns one of
+          # these. Owns the placeholder counters every `Node` mints from (see `Node#placeholder`
+          # — keeping them on the Instance rather than globally means two `Instance`s loaded in
+          # the same process never share a counter, so specs get deterministic `ph_sec_1`-style
+          # ids per fixture without any manual reset).
+          #
+          # THE THREE LINES (see the internal design doc,
+          #  section 2.4):
+          #
+          #   template = Ecoportal::API::GraphQL::Model::Template.load(client, id: page_id)
+          #   template.fields.each { |f| f.label = "#{f.label} (reviewed)" }
+          #   template.save!(client)
+          #
+          # `#save!` defaults to `simulate: true` (see its own doc) — nothing is sent to the
+          # server until the caller explicitly asks for `simulate: false`.
+          class Instance
+            attr_reader :id, :patch_ver, :stages, :phased
+
+            # @param phased [Boolean] true for a `PhasedPage` (the server's own type name),
+            #   false for a `BasicPage`/build-from-nothing. Drives whether field-level EDIT
+            #   commands need a `stageId` disambiguator (see `CommandSynthesis#stage_id_kwarg`)
+            #   -- a `Field` always carries a `#stage` reference either way (workflow-first
+            #   reads populate it for BOTH page kinds, per `Read`'s own header), so `#phased`,
+            #   not "does the field know its stage", is the real gate the schema cares about.
+            def initialize(id:, patch_ver:, stages: [], phased: false)
+              @id        = id
+              @patch_ver = patch_ver
+              @stages    = stages
+              @phased    = phased
+              @counters  = Hash.new(0)
+            end
+
+            alias_method :phased?, :phased
+
+            def next_placeholder(prefix)
+              @counters[prefix] += 1
+              "ph_#{prefix}_#{@counters[prefix]}"
+            end
+
+            class << self
+              # @param client [Ecoportal::API::GraphQL]
+              # @param id [String]
+              def load(client, id:)
+                page = Read.call(client, id)
+                from_doc(page)
+              end
+
+              # Builds an Instance from an already-fetched `page` doc (same shape `Read.call`
+              # returns) — used by both `.load` and `StagedExecutor`'s between-phase re-reads,
+              # so both paths build the SAME tree shape from the SAME doc reader.
+              def from_doc(page)
+                instance = new(id: page['id'], patch_ver: page['patchVer'], phased: page['__typename'] == 'PhasedPage')
+                Read.stages(page).each { |stage_doc| instance.stages << build_stage(instance, stage_doc) }
+                instance
+              end
+
+              private
+
+              def build_stage(instance, stage_doc)
+                stage = Stage.new(template: instance, id: stage_doc['id'], name: stage_doc['name'],
+                                  ordering: stage_doc['ordering'])
+                Array(stage_doc['sections']).each { |sec_doc| stage.sections << build_section(instance, stage, sec_doc) }
+                Array(stage_doc['forces']).each { |force_doc| stage.forces << build_force(instance, stage, force_doc) }
+                stage
+              end
+
+              def build_section(instance, stage, doc)
+                split = doc['__typename'] == 'SplitSection'
+                section = Section.new(template: instance, stage: stage, id: doc['id'],
+                                      kind: (split ? :split : :content), heading: doc['heading'],
+                                      left_heading: doc['leftHeading'], right_heading: doc['rightHeading'])
+                if split
+                  Array(doc['leftDataFields']).each { |f| section.left_fields << build_field(instance, section, stage, f) }
+                  Array(doc['rightDataFields']).each { |f| section.right_fields << build_field(instance, section, stage, f) }
+                else
+                  Array(doc['dataFields']).each { |f| section.left_fields << build_field(instance, section, stage, f) }
+                end
+                section
+              end
+
+              def build_field(instance, section, stage, doc)
+                field = Field.new(template: instance, section: section, stage: stage, id: doc['id'],
+                                  field_type: doc['__typename'], label: doc['label'], tooltip: doc['tooltip'],
+                                  description: doc['description'], required: doc['required'], hidden: doc['hidden'])
+                Array(doc['options']).each do |opt_doc|
+                  field.options << Option.new(template: instance, field: field, id: opt_doc['id'],
+                                              label: opt_doc['name'], value: opt_doc['value'])
+                end
+                field
+              end
+
+              def build_force(instance, stage, doc)
+                force = Force.new(template: instance, stage: stage, id: doc['id'], name: doc['name'],
+                                  custom_script: doc['customScript'], url: doc['url'], content_b64: doc['contentB64'])
+                Array(doc['bindings']).each do |b|
+                  force.bindings << Binding.new(template: instance, force: force, name: b['name'], reference_id: b['referenceId'])
+                end
+                Array(doc['helpers']).each do |h|
+                  force.helpers << Helper.new(template: instance, force: force, id: h['id'], name: h['name'],
+                                              file_path: h['filePath'], script: h['script'], content_b64: h['contentB64'])
+                end
+                force
+              end
+            end
+
+            # Every (non-removed) field across every stage, document order.
+            def fields
+              stages.flat_map(&:fields)
+            end
+
+            def sections
+              stages.flat_map(&:sections)
+            end
+
+            def forces
+              stages.flat_map(&:forces)
+            end
+
+            # The public diff engine — see `CommandSynthesis`'s own doc for ordering/safety.
+            def as_commands
+              CommandSynthesis.new(self).commands
+            end
+
+            def dirty?
+              !as_commands.empty?
+            end
+
+            # @param client [Ecoportal::API::GraphQL, nil] required unless `simulate: true`.
+            # @param simulate [Boolean] default true — returns the staged PLAN (stages, chunks,
+            #   command counts, placeholders) WITHOUT calling the server at all. Pass
+            #   `simulate: false` to actually execute it.
+            # @param chunk_size [Integer]
+            # @return [StagedExecutor::Plan, StagedExecutor::Result]
+            def save!(client = nil, simulate: true, chunk_size: StagedExecutor::DEFAULT_CHUNK_SIZE)
+              executor = StagedExecutor.new(self, client: client, chunk_size: chunk_size)
+              simulate ? executor.plan : executor.execute!
+            end
+
+            # Re-reads the template fresh and reports, per node this Instance currently holds
+            # (and is not flagged removed), whether the live server agrees with THIS model's
+            # own current in-memory state. Call after a `save!(simulate: false)` — compares
+            # against the model's post-save state, not the pre-save snapshot, so a call with
+            # zero pending changes never reports a false "verified" for something it never
+            # actually checked (every tracked node is still compared, `changed or not`).
+            #
+            # @param client [Ecoportal::API::GraphQL]
+            # @return [Hash] { verified: [...], mismatch: [...], missing: [...] } — each entry
+            #   `{ kind:, id:, attribute:, expected:, actual: }`. `missing` covers both "no
+            #   node with this id exists live" and "this node never resolved a real id at all"
+            #   (a save that silently no-oped).
+            def verify(client)
+              live = Instance.load(client, id: id)
+              report = { verified: [], mismatch: [], missing: [] }
+              verify_fields(live, report)
+              verify_options(live, report)
+              verify_sections(live, report)
+              report
+            end
+
+            private
+
+            def verify_fields(live, report)
+              live_by_id = live.fields.to_h { |f| [f.id, f] }
+              fields.reject(&:removed?).each { |field| compare_node(field, live_by_id[field.id], :field, %i[label tooltip description required hidden], report) }
+            end
+
+            def verify_options(live, report)
+              live_by_id = live.fields.flat_map(&:options).to_h { |o| [o.id, o] }
+              fields.reject(&:removed?).flat_map(&:options).reject(&:removed?).each do |opt|
+                compare_node(opt, live_by_id[opt.id], :option, %i[label value weight], report)
+              end
+            end
+
+            def verify_sections(live, report)
+              live_by_id = live.sections.to_h { |s| [s.id, s] }
+              sections.reject(&:removed?).each { |section| compare_node(section, live_by_id[section.id], :section, %i[heading left_heading right_heading], report) }
+            end
+
+            def compare_node(node, live_node, kind, attrs, report)
+              if node.id.nil? || live_node.nil?
+                report[:missing] << { kind: kind, id: node.id, attribute: nil, expected: nil, actual: nil }
+                return
+              end
+
+              attrs.each do |attr|
+                expected = node.public_send(attr)
+                actual   = live_node.public_send(attr)
+                entry    = { kind: kind, id: node.id, attribute: attr, expected: expected, actual: actual }
+                (expected == actual ? report[:verified] : report[:mismatch]) << entry
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/model/template/node.rb

@@ -0,0 +1,78 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Model
+        module Template
+          # Shared behaviour for every mutable node in the editable template tree (Stage,
+          # Section, Field, Option, Force, Binding, Helper). A node is either:
+          #
+          #   * LOADED — `id` is a real server id, carried in from `Read.call`. `snapshot`
+          #     freezes the mutable attributes as they were at load time, so `#dirty?` /
+          #     `#changed_attributes` can diff "now" against "as loaded" later.
+          #   * NEW — `id` is nil; the node was created in memory (`Stage#add_section`, etc.)
+          #     and has no server counterpart yet. `#ref` mints a client-chosen `placeholderId`
+          #     the first time it is asked (deterministic, `"ph_<prefix>_<n>"`, matching the
+          #     scheme `Builder::TemplateBuilder`/`Diff::CommandSynthesizer` already use,
+          #     counter owned by the root `Instance` so two loaded templates never share
+          #     counters) and memoises it — every command in the same `#as_commands` batch
+          #     that addresses this node reuses the SAME token.
+          #
+          # `#ref` is the ONE thing every command-emission method should call to address a
+          # node — never `id` directly — because it transparently upgrades from placeholder to
+          # real id the moment `StagedExecutor` resolves this node against a live re-read
+          # (`#resolve!`), without the caller needing to know which phase it is in.
+          #
+          # Including class MUST define `PLACEHOLDER_PREFIX` (a short String, e.g. `'sec'`)
+          # and `#template` (the root `Instance`, which owns the placeholder counters).
+          module Node
+            attr_reader :id
+
+            def new?
+              id.nil?
+            end
+
+            def removed?
+              !!@removed
+            end
+
+            # Flags this node for a `remove*` command. Only meaningful for a LOADED node — a
+            # NEW node that is removed before ever being saved should simply be dropped from
+            # its parent collection instead (there is nothing server-side to remove yet).
+            def remove!
+              if new?
+                raise ArgumentError, "#{self.class}: cannot remove a node that was never saved " \
+                                     '(drop it from its parent collection instead)'
+              end
+
+              @removed = true
+            end
+
+            # The token every command that addresses this node must use: the real id once
+            # known, otherwise a memoised placeholder. `StagedExecutor#resolve!` is the only
+            # code that ever calls `#resolve!` — everything downstream just calls `#ref` again
+            # and transparently gets the real id from then on.
+            def ref
+              id || placeholder
+            end
+
+            def placeholder
+              @placeholder ||= template.next_placeholder(self.class::PLACEHOLDER_PREFIX)
+            end
+
+            # Called once a live re-read has matched this NEW node to its real server id.
+            # Raises if called on an already-resolved node with a DIFFERENT id (a resolver
+            # bug, not a transient condition) — silently overwriting a resolved id would hide
+            # a mismatched cross-check upstream.
+            def resolve!(real_id)
+              raise ArgumentError, "#{self.class}: resolve! requires a real id" if real_id.nil?
+              return if id == real_id
+              raise "#{self.class}: already resolved to #{id.inspect}, cannot re-resolve to #{real_id.inspect}" if id
+
+              @id = real_id
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/model/template/option.rb

@@ -0,0 +1,49 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Model
+        module Template
+          # One option of a Select field. Read-side field name is `name` (see the gem's own
+          # `selectField` fragment, `fragment/pages/common_page_union.rb`); write-side commands
+          # (`addSelectFieldOption`/`editSelectFieldOption`) name the same thing `label` — this
+          # class always uses `label`, mapping the read-side `name` -> `label` at load time
+          # (`Read.call`), so callers never see the read/write naming split.
+          class Option
+            include Node
+
+            PLACEHOLDER_PREFIX = 'opt'.freeze
+
+            attr_reader :template, :field
+            attr_accessor :label, :value, :weight
+
+            def initialize(template:, field:, id: nil, label: nil, value: nil, weight: nil)
+              @template = template
+              @field    = field
+              @id       = id
+              @label    = label
+              @value    = value
+              @weight   = weight
+              @snapshot = snapshot_attrs.freeze
+            end
+
+            def dirty?
+              !removed? && !new? && snapshot_attrs != @snapshot
+            end
+
+            def changed_attributes
+              return {} if new? || removed?
+
+              snapshot_attrs.each_with_object({}) { |(k, v), h| h[k] = v if v != @snapshot[k] }
+            end
+
+            private
+
+            def snapshot_attrs
+              { label: label, value: value, weight: weight }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/model/template/read.rb

@@ -0,0 +1,164 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Model
+        module Template
+          # Live read for `Instance.load`/`StagedExecutor`'s between-phase re-reads.
+          #
+          # ***  PLATFORM FACT — workflow-first, DO NOT collapse onto `page.stages` alone  ***
+          #
+          # Ported verbatim (query shape) from a downstream script repo's
+          # template-fields read service, itself verified live 2026-08-01 and
+          # re-confirmed 2026-08-09: a command-bus-built template's PAGE projection can be
+          # EMPTY while its WORKFLOW carries the full structure (Workflow Builder / this gem's
+          # own `updatePageTemplate` writes workflow stage/section/field docs; the page
+          # projection does not always materialise from them), whereas a web-editor-built
+          # template DOES project page stages. Read `workflow { stages { sections } }` FIRST;
+          # fall back to the page projection only when the workflow yields nothing — never the
+          # other way round.
+          #
+          # SplitSection has NO `dataFields` — `leftDataFields`/`rightDataFields` only. Forces
+          # are read from `workflow.stages.forces` only (`18_template_editor_save_path.md`
+          # section A.1, `TemplateStageFields.forces`); the page projection carries no forces
+          # at all, so there is no fallback for that part of the read.
+          #
+          # `Helper`'s own five fields -- `id name filePath script contentB64` -- are LIVE-
+          # VERIFIED (not merely mirrored from the write side): a downstream script repo's
+          # template force-read case selects
+          # `helpers { id name filePath script contentB64 }` on exactly this same
+          # `forces` field, and that read has run live against pre_prod across 47 templates
+          # (that file's own header, lines 29-31/90). Use these five with confidence.
+          #
+          # UNVERIFIED against a live schema this session: any `Force` field beyond the
+          # `Helper` sub-fields cited above (e.g. a top-level `script` alongside
+          # `customScript`, or a plain `url`/`contentB64` on the force itself) -- cite before
+          # relying on anything not confirmed above.
+          module Read
+            STRUCTURE_QUERY = <<~GRAPHQL.freeze
+              query TemplateModelRead($id: ID!) {
+                currentOrganization {
+                  page(id: $id, showHiddenData: true) {
+                    __typename
+                    ... on BasicPage {
+                      id
+                      name
+                      patchVer
+                      workflow { stages { ...wfStage } }
+                      sections { ...sectionFields }
+                    }
+                    ... on PhasedPage {
+                      id
+                      name
+                      patchVer
+                      workflow { stages { ...wfStage } }
+                      stages { id name ordering sections { ...sectionFields } }
+                    }
+                  }
+                }
+              }
+
+              fragment wfStage on Stage {
+                id
+                name
+                ordering
+                sections { ...sectionFields }
+                forces {
+                  id
+                  name
+                  customScript
+                  url
+                  contentB64
+                  bindings { name referenceId }
+                  helpers { id name filePath script contentB64 }
+                }
+              }
+
+              fragment sectionFields on SectionUnion {
+                __typename
+                ... on ContentSection {
+                  id
+                  heading
+                  dataFields { ...tf }
+                }
+                ... on SplitSection {
+                  id
+                  heading
+                  leftHeading
+                  rightHeading
+                  leftDataFields { ...tf }
+                  rightDataFields { ...tf }
+                }
+              }
+
+              fragment tf on DataFieldUnion {
+                __typename
+                ... on DataFieldsInterface {
+                  id
+                  label
+                  description
+                  tooltip
+                  hidden
+                  required
+                }
+                ... on Select {
+                  options { id value name }
+                }
+              }
+            GRAPHQL
+
+            class << self
+              # @param client [Ecoportal::API::GraphQL] the top-level gem client (has
+              #   `#client` / `.http_client`, matching every other read in this gem).
+              # @param id [String] the template's page id.
+              # @return [Hash] the raw `page` doc (string keys, as the server sent it).
+              def call(client, id)
+                raw  = http(client).execute(STRUCTURE_QUERY, variables: { id: id })
+                page = raw.dig('data', 'currentOrganization', 'page')
+                raise "Template '#{id}' not readable as page" unless page
+
+                page
+              end
+
+              # Fields in document order, workflow-first, exactly `TemplateFieldsRead.fields`'s
+              # own semantics (kept as a module method so `StagedExecutor`'s re-read
+              # cross-checks can call it against a freshly re-fetched `page` doc without going
+              # through the whole `Instance` construction).
+              #
+              # @return [Array<Hash>] each entry carries stage_id/section_id/section_side
+              #   alongside the field's own doc, in document order.
+              def stages(page)
+                from_workflow = Array(page.dig('workflow', 'stages'))
+                return from_workflow unless from_workflow.empty?
+
+                fallback_stages(page)
+              end
+
+              private
+
+              # Accepts, in order of preference: the top-level `Ecoportal::API::GraphQL`
+              # object (`client.client.http_client`), the inner
+              # `Common::GraphQL::Client` directly (`client.http_client`), or a bare
+              # `#execute(query, variables:) -> Hash` duck (a spec double) as-is.
+              def http(client)
+                return client.client.http_client if client.respond_to?(:client) && client.client.respond_to?(:http_client)
+                return client.http_client if client.respond_to?(:http_client)
+
+                client
+              end
+
+              def fallback_stages(page)
+                case page['__typename']
+                when 'PhasedPage' then Array(page['stages'])
+                when 'BasicPage'
+                  [{ 'id' => nil, 'name' => nil, 'ordering' => 0, 'sections' => Array(page['sections']), 'forces' => [] }]
+                else
+                  []
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/model/template/section.rb

@@ -0,0 +1,82 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Model
+        module Template
+          # One section. `kind` is `:content` (single `fields` list) or `:split` (`left_fields`
+          # / `right_fields`, each independently addressable — a `SplitSection` has NO
+          # `dataFields` of its own, see `Read.call`'s header). `#fields` always returns the
+          # flattened, document-ordered list (left then right, for a split section) — the ONE
+          # place callers should iterate unless they specifically need a side.
+          class Section
+            include Node
+
+            PLACEHOLDER_PREFIX = 'sec'.freeze
+
+            attr_reader :template, :stage, :kind, :layout, :left_fields, :right_fields, :pending_move
+            attr_accessor :heading, :left_heading, :right_heading
+
+            def initialize(template:, stage:, id: nil, kind: :content, layout: nil,
+                           heading: nil, left_heading: nil, right_heading: nil)
+              @template      = template
+              @stage         = stage
+              @id            = id
+              @kind          = kind
+              @layout        = layout
+              @heading       = heading
+              @left_heading  = left_heading
+              @right_heading = right_heading
+              @left_fields   = []
+              @right_fields  = []
+              @pending_move  = nil
+              @snapshot      = snapshot_attrs.freeze
+            end
+
+            # Document-ordered fields. For a :content section this IS `left_fields`; for a
+            # :split section it is left-then-right (matches `Read.call`'s own document-order
+            # flattening, so `#fields` here and the loaded order agree).
+            def fields
+              kind == :split ? left_fields + right_fields : left_fields
+            end
+
+            def add_field(field_type:, label: nil, column: nil, side: nil, **kargs)
+              field = Field.new(template: template, section: self, stage: stage,
+                                field_type: field_type, label: label, column: column, **kargs)
+              (side == :right ? right_fields : left_fields) << field
+              field
+            end
+
+            # Records the intent to reposition this (existing) section relative to `anchor`
+            # (another Section) — emitted as ONE `reorderSection` command as a per-stage
+            # TRAILER (after every structural add/remove in the same stage), because the
+            # server rewrites EVERY sibling's weight on a reorder
+            # (`18_template_editor_save_path.md` section C.1) — running it before a same-batch
+            # `addStageSection` would have its effect immediately overwritten by the next
+            # section's own weight assignment.
+            def move(anchor:, position:)
+              raise ArgumentError, "position must be 'BEFORE' or 'AFTER'" unless %w[BEFORE AFTER].include?(position)
+
+              @pending_move = { anchor: anchor, position: position }
+            end
+
+            def dirty?
+              !removed? && !new? && snapshot_attrs != @snapshot
+            end
+
+            def changed_attributes
+              return {} if new? || removed?
+
+              snapshot_attrs.each_with_object({}) { |(k, v), h| h[k] = v if v != @snapshot[k] }
+            end
+
+            private
+
+            def snapshot_attrs
+              { heading: heading, left_heading: left_heading, right_heading: right_heading }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/model/template/stage.rb

@@ -0,0 +1,49 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Model
+        module Template
+          # One workflow stage. `editStage`/`moveStage` exist server-side but are not wired to
+          # a mutable accessor here yet — out of scope for this pass (see the model's own
+          # design doc, "not yet implemented"); `name`/`ordering` are captured read-only for
+          # display and cross-checks.
+          class Stage
+            include Node
+
+            PLACEHOLDER_PREFIX = 'stg'.freeze
+
+            attr_reader :template, :sections, :forces, :name, :ordering
+
+            def initialize(template:, id: nil, name: nil, ordering: nil)
+              @template = template
+              @id       = id
+              @name     = name
+              @ordering = ordering
+              @sections = []
+              @forces   = []
+            end
+
+            def add_section(kind: :content, layout: nil, heading: nil, left_heading: nil, right_heading: nil)
+              section = Section.new(template: template, stage: self, kind: kind, layout: layout,
+                                    heading: heading, left_heading: left_heading, right_heading: right_heading)
+              sections << section
+              section
+            end
+
+            def add_force(name: nil, custom_script: nil, url: nil, content_b64: nil)
+              force = Force.new(template: template, stage: self, name: name, custom_script: custom_script,
+                                url: url, content_b64: content_b64)
+              forces << force
+              force
+            end
+
+            # Every field across every (non-removed) section of this stage, document order.
+            def fields
+              sections.reject(&:removed?).flat_map(&:fields)
+            end
+          end
+        end
+      end
+    end
+  end
+end