eco-helpers 3.2.16 → 3.2.17

data/lib/eco/api/usecases/graphql/samples/pages/register/target_oozes_update_case.rb

@@ -0,0 +1,163 @@
+module Eco::API::UseCases::GraphQL::Samples::Pages
+  # Native GraphQL re-expression of OozeSamples::TargetOozesUpdateCase.
+  #
+  # Where Register::Base scopes work to a register and iterates its entries via a
+  # cursor search, this case takes an explicit list of target page ids from a CSV
+  # (`options[:source][:file]`, first column, header dropped) and processes each of
+  # those pages. It reproduces the SHAPE of the v2 TargetOozesUpdateCase:
+  #   * id-batching (`batched_target_ids`)
+  #   * a preview with duplicate detection + interactive proceed prompt
+  #   * fetch-per-id (`graphql.pages.get`), dedup-by-id, retrieved/non-retrieved KPIs
+  #   * hand each fetched page to `process_page` (a.k.a. `process_ooze`)
+  #
+  # As with Register::Base, the v2 batch_queue / enqueue / queue_shift machinery is
+  # intentionally dropped: the GraphQL update path is per-page. `update_page(page)`
+  # (from Page::Base) persists changes as the subclass makes them.
+  #
+  # == Subclass interface
+  #
+  #   class Custom::UseCase::TOOCSCoding < Eco::API::UseCases::GraphQL::Samples::Pages::Register::TargetOozesUpdateCase
+  #     name 'toocs-coding'
+  #
+  #     def process_page(page)
+  #       fld = page.components.get_by_name('TOOCS Code')
+  #       return skip('no field') unless fld
+  #       fld.value = merge_field_values(fld, options.dig(:source, :value))
+  #       update_page(page)
+  #     end
+  #   end
+  #
+  # The CSV file is provided via `options[:source][:file]`.
+  class Register::TargetOozesUpdateCase < Register::Base
+    name 'graphql-target-oozes-update-case'
+    type :other
+
+    attr_reader :non_retrieved_pages
+
+    # Entry point — mirrors Register::Base#process but iterates target ids rather
+    # than a register search.
+    def process
+      init_kpis
+      target_ids_preview
+      each_target_page do |page|
+        process_page(page)
+        @processed_pages += 1
+      end
+      log_kpis
+    end
+
+    protected
+
+    # Fetch and iterate each target page by id, in batches. Counts retrieved /
+    # non-retrieved and dedups by id (v2 parity).
+    def each_target_page
+      batched_target_ids do |ids|
+        ids.each do |id|
+          if page_result_ids[id]
+            @dupped_search_pages += 1
+          else
+            page_result_ids[id] = true
+            @total_pages += 1
+          end
+
+          if (page = fetch_page(id))
+            @retrieved_pages += 1
+            yield page
+          else
+            @non_retrieved_pages += 1
+            log(:warn) { "Could not get page #{id}" }
+          end
+        end
+      end
+    end
+
+    # Fetch one page by id via the GraphQL compat client. Wrapped so a bad id does
+    # not abort the whole run.
+    # @return [Object, nil] the page model, or nil when it could not be fetched.
+    def fetch_page(id)
+      with_rescue("page #{id}") do
+        graphql.pages.get(id)
+      end
+    end
+
+    private
+
+    # Yields the target ids in slices of `batch_size`.
+    def batched_target_ids
+      msg = "Missing block. It yields in slices of #{self.class.batch_size} ids"
+      raise ArgumentError, msg unless block_given?
+
+      pool = []
+      target_ids.each do |id|
+        pool << id
+        if pool.length >= self.class.batch_size
+          yield(pool)
+          pool = []
+        end
+      end
+      yield(pool) unless pool.empty?
+    end
+
+    # Preview: total count + duplicate detection + interactive proceed prompt
+    # (v2-faithful — matches TargetOozesUpdateCase#target_ids_preview).
+    def target_ids_preview
+      dups = target_ids.select {|id| target_ids.count(id) > 1}
+      @total_search_pages  = target_ids.count
+      @dupped_search_pages = 0
+
+      dups_str = dups.any? ? "There are #{dups.count} duplicated ids" : 'No duplicates detected'
+      msg = "Total target entries: #{target_ids.count} (#{dups_str})"
+
+      default_answer = session.config.run_mode_remote? ? 'Y' : 'N'
+
+      session.prompt_user(
+        'Do you want to proceed (y/N):',
+        explanation: msg,
+        default:     default_answer,
+        timeout:     10
+      ) do |res|
+        unless res.upcase.start_with?('Y')
+          puts '...'
+          log(:info) { 'Aborting script...' }
+          exit(0)
+        end
+      end
+    end
+
+    # The list of target page ids (first CSV column, header dropped).
+    def target_ids
+      @target_ids ||= input_csv.columns.first[1..]
+    end
+
+    def input_csv
+      @input_csv ||= Eco::CSV.read(options.dig(:source, :file))
+    end
+
+    # #each_page is register-search based (inherited from Register::Base) and is NOT
+    # the iteration path here — target ids come from the CSV. Guard against accidental
+    # use so a subclass mixing the two gets a clear error rather than a silent org scan.
+    def each_page(*)
+      raise NotImplementedError,
+            "#{self.class} iterates target ids from a CSV — use #each_target_page, not #each_page"
+    end
+
+    def init_kpis
+      super
+      @non_retrieved_pages = 0
+    end
+
+    def kpis_message
+      [
+        'Run end:',
+        "  * Target entries:  #{total_search_pages}",
+        "  * Duplicated:      #{dupped_search_pages}",
+        "  * Retrieved:       #{retrieved_pages}",
+        "  * Could not get:   #{non_retrieved_pages}",
+        "  * Processed:       #{processed_pages}",
+        "  * Updated:         #{updated_pages} (of #{total_pages} unique)",
+        "  * Skipped:         #{skipped_pages}",
+        "  * Failed:          #{failed_pages}"
+      ].join("\n")
+    end
+  end
+end

data/lib/eco/api/usecases/graphql/samples/pages/register.rb

@@ -0,0 +1,8 @@
+module Eco::API::UseCases::GraphQL::Samples::Pages
+  module Register
+  end
+end
+
+require_relative 'register/base'
+require_relative 'register/target_oozes_update_case'
+require_relative 'register/migration_case'

data/lib/eco/api/usecases/graphql/samples/pages/template/base.rb

@@ -0,0 +1,70 @@
+module Eco::API::UseCases::GraphQL::Samples::Pages
+  # Build-from-scratch template (workflow) construction use case.
+  #
+  # A subclass declares the desired template structure in #declare(emitter) using the
+  # CommandEmitter DSL; the base turns it into an ordered command batch and applies it via
+  # graphql.template.create / update (executeWorkflowCommands). `simulate?` previews the batch
+  # without writing. The emitted batch (#desired_commands) is unit-testable with no live client.
+  #
+  #   class Custom::UseCase::BuildIncidentTemplate < Samples::Pages::Template::Base
+  #     name 'build-incident-template'
+  #
+  #     def declare(t)
+  #       t.stage(name: 'Report', ordering: 0) do |stage|
+  #         stage.section(layout: 'content') do |section|
+  #           section.field(label: 'Description', field_type: 'plain_text')
+  #         end
+  #       end
+  #     end
+  #   end
+  class Template::Base < Eco::API::UseCases::GraphQL::Base
+    name 'graphql-template-base'
+    type :other
+
+    require_relative 'command_emitter'
+
+    def process
+      commands = desired_commands
+      if simulate?
+        log(:info) { preview_message(commands) }
+        return nil
+      end
+      apply(commands)
+    end
+
+    # == Subclass override point ================================================
+
+    # Declare the desired template structure onto the given CommandEmitter.
+    def declare(_emitter)
+      raise NotImplementedError, "Implement #declare(emitter) in #{self.class}"
+    end
+
+    # The ordered command batch this template would apply. Pure — no client needed.
+    def desired_commands
+      emitter = CommandEmitter.new
+      declare(emitter)
+      emitter.commands
+    end
+
+    protected
+
+    # Persist a fresh template from the command batch. Override to #update an existing one.
+    def apply(commands)
+      graphql.template.create(commands: commands)
+    end
+
+    # Update an existing template model with the command batch.
+    def apply_update(model, commands)
+      graphql.template.update(model, commands: commands)
+    end
+
+    private
+
+    def preview_message(commands)
+      [
+        "Simulate — would apply #{commands.size} workflow command(s):",
+        *commands.map { |c| "  * #{c.keys.first}: #{c.values.first.inspect}" }
+      ].join("\n")
+    end
+  end
+end

data/lib/eco/api/usecases/graphql/samples/pages/template/command_emitter.rb

@@ -0,0 +1,139 @@
+module Eco::API::UseCases::GraphQL::Samples::Pages
+  module Template
+    # Declarative build-from-scratch emitter for template (workflow) structure.
+    #
+    # Mirrors the *shape* of the location diff->commands engine (samples/location/command), but the
+    # id-threading is **placeholder-based**, not post-hoc newId-remap: each new node is given a
+    # client-chosen `placeholderId`, and later commands in the SAME batch reference it. The gem's
+    # executeWorkflowCommands resolves placeholders intra-batch. See the gem's PHASE0-FINDINGS.md.
+    #
+    # Commands are emitted in dependency order via depth-first DSL evaluation:
+    #   addStage -> (per section) addSection, addStageSection -> (per field) addField
+    #     -> (per option) addSelectFieldOption ; then forces: addForce -> (per binding) addBinding.
+    #
+    # Usage:
+    #   emitter = CommandEmitter.new
+    #   emitter.stage(name: 'Report', ordering: 0) do |stage|
+    #     stage.section(layout: 'content') do |section|
+    #       section.field(label: 'Notes', field_type: 'plain_text')
+    #       section.field(label: 'Risk', field_type: 'select') do |field|
+    #         field.option(label: 'High', weight: 10)
+    #       end
+    #     end
+    #   end
+    #   emitter.commands # => ordered Array of FINAL built { commandKey => kwargs } commands
+    #
+    # The output is fed DIRECTLY to graphql.template.create(commands:) / update(model, commands:).
+    # It is already built via WorkflowCommand.build — do NOT re-run it through build_commands
+    # (that normaliser is for hand-authored raw specs and is non-idempotent for key-renaming
+    # commands such as addSelectFieldOption: data_field_id -> dataFieldId).
+    class CommandEmitter
+      def initialize
+        @commands = []
+        @counters = Hash.new(0)
+      end
+
+      # @return [Array<Hash>] ordered command specs, each { commandKey => kwargs }
+      attr_reader :commands
+
+      # Declare a stage. Yields a StageBuilder for nested sections.
+      def stage(name:, ordering: nil, &block)
+        placeholder = allocate(:stg)
+        emit(:addStage, placeholderId: placeholder, name: name, ordering: ordering)
+        StageBuilder.new(self, placeholder).tap { |b| block&.call(b) }
+        placeholder
+      end
+
+      # Declare a force at template level. Yields a ForceBuilder for bindings.
+      def force(name:, custom_script: nil, url: nil, content_b64: nil, &block)
+        placeholder = allocate(:frc)
+        emit(:addForce, placeholderId: placeholder, name: name, customScript: custom_script,
+                        url: url, contentB64: content_b64)
+        ForceBuilder.new(self, placeholder).tap { |b| block&.call(b) }
+        placeholder
+      end
+
+      # --- internal API used by the nested builders ---------------------------
+
+      # Allocate the next placeholder id for a node kind (:stg, :sec, :fld, :frc, :bnd).
+      def allocate(kind)
+        "#{kind}#{@counters[kind] += 1}"
+      end
+
+      # Build + append one command via the gem's WorkflowCommand contract.
+      # The gem constant is resolved lazily (at call time, not load time) — the gem's GraphQL
+      # namespace is not yet loaded while this file is being required.
+      def emit(command_key, **kwargs)
+        @commands << Ecoportal::API::GraphQL::Input::WorkflowCommand.build(command_key, **kwargs)
+      end
+
+      # Nested builders — each holds its parent's placeholder and appends in-order.
+
+      class StageBuilder
+        def initialize(emitter, stage_id)
+          @emitter  = emitter
+          @stage_id = stage_id
+        end
+
+        # A section is created independently, then linked into this stage.
+        def section(layout: 'content', &block)
+          section_id = @emitter.allocate(:sec)
+          @emitter.emit(:addSection, placeholderId: section_id, layout: layout)
+          @emitter.emit(:addStageSection, stageId: @stage_id, sectionId: section_id)
+          SectionBuilder.new(@emitter, @stage_id, section_id).tap { |b| block&.call(b) }
+          section_id
+        end
+      end
+
+      class SectionBuilder
+        def initialize(emitter, stage_id, section_id)
+          @emitter    = emitter
+          @stage_id   = stage_id
+          @section_id = section_id
+        end
+
+        # `description` / `required` are accepted for forward-compatibility with the CSV-build
+        # identity convention (hidden-field + description). NOTE: the RELEASED gem's addField input
+        # (`Input::WorkflowCommand::AddField::VALID_KEYS`) currently slices to
+        # placeholderId/fieldType/label/stageId/sectionId/column and compacts everything else away —
+        # so today these pass-throughs are DROPPED by the gem contract (harmless no-op). They are wired
+        # here so that, once the gem's addField gains a description key, no emitter change is needed.
+        def field(label:, field_type:, column: 0, description: nil, required: nil, &block)
+          field_id = @emitter.allocate(:fld)
+          @emitter.emit(:addField, placeholderId: field_id, fieldType: field_type, label: label,
+                                   stageId: @stage_id, sectionId: @section_id, column: column,
+                                   description: description, required: required)
+          FieldBuilder.new(@emitter, field_id).tap { |b| block&.call(b) }
+          field_id
+        end
+      end
+
+      class FieldBuilder
+        def initialize(emitter, field_id)
+          @emitter  = emitter
+          @field_id = field_id
+        end
+
+        # Select-field option. dataFieldId threads the (placeholder) field id.
+        def option(label:, weight: nil)
+          @emitter.emit(:addSelectFieldOption, data_field_id: @field_id, label: label, weight: weight)
+          @field_id
+        end
+      end
+
+      class ForceBuilder
+        def initialize(emitter, force_id)
+          @emitter  = emitter
+          @force_id = force_id
+        end
+
+        def binding(name:, reference_id: nil, type: nil)
+          binding_id = @emitter.allocate(:bnd)
+          @emitter.emit(:addBinding, placeholderId: binding_id, forceId: @force_id, name: name,
+                                     referenceId: reference_id, type: type)
+          binding_id
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/usecases/graphql/samples/pages/template/csv_build/builder.rb

@@ -0,0 +1,126 @@
+module Eco::API::UseCases::GraphQL::Samples::Pages::Template
+  module CsvBuild
+    # CSV → template BUILD pipeline.
+    #
+    # Ties the pieces together: a `Parser` turns a columnar CSV into a stage/section/field tree, this
+    # Builder replays that tree onto the EXISTING `Template::CommandEmitter` (reused verbatim — same
+    # placeholder-id threading the create path already relies on), and then hands the resulting ordered
+    # `WorkflowCommand` batch to the released gem's `Builder::Template#create(commands:)`.
+    #
+    # Offline / dry-run by DEFAULT — real creation needs credentials, so `build` only assembles and
+    # returns the command batch; `create!` is the explicit live path (requires a gem `Builder::Template`
+    # or `GraphQL#template` facade).
+    #
+    #   builder  = CsvBuild::Builder.from_csv(csv_string)
+    #   commands = builder.commands            # ordered { commandKey => kwargs } batch, offline
+    #   # live (needs creds):
+    #   builder.create!(graphql.template)      # => gem create mutation response
+    #
+    # SECTION / FIELD IDENTITY: each field's `description` (from FormatMap) is passed to the emitter's
+    # `field(description:)`, and a hidden anchor per section carries the section identity — so a rebuilt
+    # template stays pair-able against a prior version by the diff engine. When the field type is
+    # `select`, the parsed options are emitted as addSelectFieldOption commands.
+    #
+    # ⚠ HONEST LIMITATION: the RELEASED gem's `addField` input drops any key outside
+    # placeholderId/fieldType/label/stageId/sectionId/column (see CommandEmitter#field note). So today
+    # the `description` identity token is NOT persisted through addField — the hidden ANCHOR FIELD's
+    # presence (its label) is the only identity signal that currently survives to the batch. The
+    # description wiring is in place so identity flows end-to-end the moment the gem's addField input
+    # gains a description key. Until then, section/field identity relies on the anchor + heading/label.
+    class Builder
+      # Hidden marker field type used to anchor SECTION identity across rebuilds (identity convention:
+      # hidden-field + description). Kept as a constant so it is trivial to retune when the real format
+      # / platform convention for the anchor is confirmed.
+      SECTION_ANCHOR_TYPE  = 'hidden'.freeze
+      SECTION_ANCHOR_LABEL = '__section_id'.freeze
+
+      def self.from_csv(csv_string, **opts)
+        new(Parser.new(csv_string), **opts)
+      end
+
+      def self.from_file(path, **opts)
+        new(Parser.from_file(path), **opts)
+      end
+
+      # @param parser [Parser]
+      # @param section_anchors [Boolean] emit a hidden anchor field per section for stable identity
+      #   (default true — the CSV-pipeline identity convention). Set false for a plain build.
+      def initialize(parser, section_anchors: true)
+        @parser          = parser
+        @section_anchors = section_anchors
+      end
+
+      # The ordered command batch — PURE, no client needed. This is what specs assert against.
+      def commands
+        @commands ||= begin
+          emitter = CommandEmitter.new
+          emit_tree(emitter)
+          emitter.commands
+        end
+      end
+
+      # LIVE build (needs creds). `template_facade` is the gem `Builder::Template` (a.k.a.
+      # `graphql.template`) exposing `create(commands:)`.
+      def create!(template_facade, &block)
+        unless template_facade.respond_to?(:create)
+          raise ArgumentError,
+                'template facade must respond to #create(commands:)'
+        end
+
+        template_facade.create(commands: commands, &block)
+      end
+
+      # Human preview of the batch (for a dry-run / simulate log).
+      def preview
+        ["CSV build — #{commands.size} workflow command(s):",
+         *commands.map { |c| "  * #{c.keys.first}: #{c.values.first.inspect}" }].join("\n")
+      end
+
+      private
+
+      def emit_tree(emitter)
+        @parser.tree.each do |stage|
+          emitter.stage(name: stage[:name], ordering: stage[:ordering]) do |stage_builder|
+            stage[:sections].each { |section| emit_section(stage_builder, section) }
+          end
+        end
+      end
+
+      def emit_section(stage_builder, section)
+        stage_builder.section(layout: section[:layout]) do |section_builder|
+          emit_section_anchor(section_builder, section) if @section_anchors
+          section[:fields].each { |field| emit_field(section_builder, field) }
+        end
+      end
+
+      # Hidden anchor field carrying the section identity in its description (identity convention).
+      def emit_section_anchor(section_builder, section)
+        section_builder.field(
+          label:       SECTION_ANCHOR_LABEL,
+          field_type:  SECTION_ANCHOR_TYPE,
+          description: section_identity(section)
+        )
+      end
+
+      def emit_field(section_builder, field)
+        section_builder.field(
+          label:       field.label,
+          field_type:  field.type,
+          column:      field.column,
+          required:    field.required,
+          description: field.description
+        ) do |field_builder|
+          Array(field.options).each do |opt|
+            field_builder.option(label: opt[:label], weight: opt[:weight])
+          end
+        end
+      end
+
+      # Stable section identity token. Uses the section heading; a hidden anchor field carries it so
+      # the diff/pairing engine can re-home the section on a rebuild.
+      def section_identity(section)
+        "section:#{section[:heading]}"
+      end
+    end
+  end
+end

data/lib/eco/api/usecases/graphql/samples/pages/template/csv_build/format_map.rb

@@ -0,0 +1,108 @@
+module Eco::API::UseCases::GraphQL::Samples::Pages::Template
+  module CsvBuild
+    # ISOLATED column-format mapping for the CSV → template build pipeline.
+    #
+    # ============================ IMPORTANT / TODO ============================
+    # The EXACT columnar CSV format for the ~300-template bulk build is due ~mid-July 2026 and is NOT
+    # yet confirmed. This class is the SINGLE place the assumed format is encoded, precisely so that
+    # when the real format lands, only THIS file (and its spec) needs to change — the Parser and
+    # Builder are written against the neutral intermediate `RowSpec`, not against column names.
+    #
+    # Assumed format (documented here, one row per FIELD, hierarchy carried on each row):
+    #
+    #   stage,stage_ordering,section,section_ordering,section_layout,
+    #   field_label,field_type,field_required,field_column,field_description,field_options
+    #
+    #   * `field_type`     — a template field type accepted by addField (e.g. plain_text, select,
+    #                        date, number, gauge, rich_text, people, ...). Passed through verbatim.
+    #   * `field_options`  — for select-type fields: pipe-separated `label:weight` pairs,
+    #                        e.g. "High:10|Medium:5|Low:0". Weight optional ("High|Medium|Low").
+    #   * `field_description` — carries the SECTION/FIELD IDENTITY convention (see below).
+    #
+    # SECTION / FIELD IDENTITY CONVENTION (per the CSV-pipeline project notes): stable identity for a
+    # section/field across rebuilds is expressed via a HIDDEN marker field + a DESCRIPTION token, not
+    # via the volatile Mongo id. The parser threads `field_description` through so the builder can
+    # stamp a deterministic identity token; sections inherit identity from their heading + a hidden
+    # anchor field. This keeps a rebuilt template pair-able against a prior version by the diff engine.
+    # ==========================================================================
+    #
+    # To adapt to the real format: change COLUMNS + the `#value`/`#options` readers here. Everything
+    # downstream consumes `RowSpec`, which is format-agnostic.
+    module FormatMap
+      # Logical field  =>  CSV header name (assumed). CHANGE HERE when the real format arrives.
+      COLUMNS = {
+        stage:             'stage',
+        stage_ordering:    'stage_ordering',
+        section:           'section',
+        section_ordering:  'section_ordering',
+        section_layout:    'section_layout',
+        field_label:       'field_label',
+        field_type:        'field_type',
+        field_required:    'field_required',
+        field_column:      'field_column',
+        field_description: 'field_description',
+        field_options:     'field_options'
+      }.freeze
+
+      # Delimiters (assumed). CHANGE HERE if the real format differs.
+      OPTIONS_DELIMITER = '|'.freeze
+      OPTION_WEIGHT_SEPARATOR = ':'.freeze
+
+      # Neutral, format-agnostic row: what the Builder consumes. Only THIS is passed downstream.
+      RowSpec = Struct.new(:stage, :stage_ordering, :section, :section_ordering, :section_layout,
+                           :field_label, :field_type, :field_required, :field_column,
+                           :field_description, :field_options, keyword_init: true)
+
+      module_function
+
+      # Map one CSV row (a Hash keyed by header string) to a RowSpec.
+      def row_spec(row)
+        RowSpec.new(
+          stage:             value(row, :stage),
+          stage_ordering:    integer(row, :stage_ordering),
+          section:           value(row, :section),
+          section_ordering:  integer(row, :section_ordering),
+          section_layout:    value(row, :section_layout) || 'content',
+          field_label:       value(row, :field_label),
+          field_type:        value(row, :field_type),
+          field_required:    truthy?(row, :field_required),
+          field_column:      integer(row, :field_column) || 0,
+          field_description: value(row, :field_description),
+          field_options:     options(value(row, :field_options))
+        )
+      end
+
+      # Parse the options cell into [ { label:, weight: }, ... ]. Empty → [].
+      def options(cell)
+        return [] if cell.nil? || cell.to_s.strip.empty?
+
+        cell.to_s.split(OPTIONS_DELIMITER).map do |token|
+          label, weight = token.split(OPTION_WEIGHT_SEPARATOR, 2).map(&:strip)
+          { label: label, weight: (weight && !weight.empty? ? Integer(weight, exception: false) : nil) }
+        end
+      end
+
+      def value(row, logical)
+        header = COLUMNS.fetch(logical)
+        raw    = row[header]
+        raw = row[header.to_sym] if raw.nil? && row.respond_to?(:key?)
+        return nil if raw.nil?
+
+        str = raw.to_s.strip
+        str.empty? ? nil : str
+      end
+
+      def integer(row, logical)
+        raw = value(row, logical)
+        raw && Integer(raw, exception: false)
+      end
+
+      def truthy?(row, logical)
+        raw = value(row, logical)
+        return false if raw.nil?
+
+        %w[1 true yes y required].include?(raw.downcase)
+      end
+    end
+  end
+end