eco-helpers 3.2.14 → 3.2.23

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

@@ -0,0 +1,181 @@
+module Eco::API::UseCases::GraphQL::Samples::Pages
+  # Native GraphQL re-expression of OozeSamples::RegisterUpdateCase.
+  #
+  # Register-scoped page processing: iterate the entries of a register in
+  # cursor-paginated batches, hand each page to `process_page` (a.k.a.
+  # `process_ooze` for naming parity with the v2 case), and track KPI counters
+  # over the whole run. Supports creating new entries via the native Creatable.
+  #
+  # This reproduces the SHAPE of RegisterUpdateCase (batched search, dedup-by-id,
+  # search/retrieved/updated/created/failed counters, a dry-run preview) natively,
+  # without the Ecoportal::API::V2 queue/enqueue coupling: the GraphQL update path
+  # is per-page (graphql.pages.update) rather than a batched patch queue, so the
+  # v2 batch_queue / enqueue / queue_shift machinery is intentionally dropped.
+  #
+  # == Subclass interface
+  #
+  #   class Custom::UseCase::CloseOldEntries < Eco::API::UseCases::GraphQL::Samples::Pages::Register::Base
+  #     name 'close-old-entries'
+  #     register_id 'REG_ABC123'
+  #     batch_size 25
+  #
+  #     def process_page(page)
+  #       return skip('not stale') unless stale?(page)
+  #       page.name = "[CLOSED] #{page.name}"
+  #       update_page(page)
+  #     end
+  #   end
+  #
+  # `register_id` may also come from `options[:source][:register_id]` (v2 parity),
+  # which takes precedence over the class-level declaration when present.
+  class Register::Base < Page::Base
+    include Eco::API::UseCases::GraphQL::Helpers::Pages::Shortcuts
+    include Eco::API::UseCases::GraphQL::Helpers::Pages::OozeHandlers
+    include Eco::API::UseCases::GraphQL::Helpers::Pages::Rescuable
+    include Eco::API::UseCases::GraphQL::Helpers::Pages::Creatable
+
+    name 'graphql-register-base'
+    type :other
+
+    class << self
+      def batch_size(size = nil)
+        @batch_size ||= 25
+        return @batch_size unless size
+
+        @batch_size = size
+      end
+    end
+
+    attr_reader :total_search_pages, :dupped_search_pages
+    attr_reader :retrieved_pages, :page_result_ids
+    attr_reader :created_pages, :page_create_attempts
+
+    # Entry point — called by GraphQL::Base#main.
+    def process
+      init_kpis
+      results_preview
+      each_page do |page|
+        process_page(page)
+        @processed_pages += 1
+      end
+      log_kpis
+    end
+
+    # == Subclass override points ==============================================
+
+    # Transform or act on one page. Call update_page(page) to persist changes.
+    # Alias `process_ooze` is provided for naming parity with the v2 case.
+    def process_page(_page)
+      raise NotImplementedError, "Implement #process_page in #{self.class}"
+    end
+
+    # Naming-parity alias for the v2 case. Forwards (rather than alias_method) so a
+    # subclass overriding #process_page is honoured when called as #process_ooze.
+    def process_ooze(page)
+      process_page(page)
+    end
+
+    # Return the register id to scope the search to.
+    # `options[:source][:register_id]` (v2 parity) wins over the class declaration.
+    def register_id
+      options.dig(:source, :register_id) || self.class.register_id
+    end
+
+    # Return a SearchConf for the page search. Override to add filters.
+    # Default: scoped to register_id (raises if none configured — a register case
+    # without a register would silently scan the whole org).
+    def search_conf
+      reg = register_id
+      raise ArgumentError, 'No register_id configured (class register_id or options[:source][:register_id])' unless reg
+
+      sc.new.filter(in_register(reg))
+    end
+
+    protected
+
+    # Typed value merge for a GraphQL data field. Convenience over OozeHandlers#merge_values
+    # that reads the field's own #type so a subclass need not pass it explicitly.
+    #
+    #   fld = page.components.get_by_name('Notes')
+    #   fld.value = merge_field_values(fld, incoming_notes)
+    #
+    # @param field [#type] a GraphQL DataField (or anything responding to #type).
+    # @param append [Object] the value to merge onto the field's current value.
+    # @param origin [Object] the base value; defaults to the field's current #value.
+    # @param delimiter [String] delimiter for :delimiter-strategy types.
+    # @return [Object] the merged value.
+    def merge_field_values(field, append, origin: nil, delimiter: "\n")
+      base = origin.nil? && field.respond_to?(:value) ? field.value : origin
+      merge_values(base, append, type: field, delimiter: delimiter)
+    end
+
+    # Launches the actual creation of the entry (hook driven by Creatable).
+    # Respects simulate? for dry-run; on live create, bumps the created counter.
+    # @return [Ecoportal::API::GraphQL::Compat::PageReference, false]
+    def create_ooze(draft, template_id: draft&.template_id)
+      @page_create_attempts += 1
+      if simulate?
+        dry_run_feedback(draft)
+        return false
+      end
+
+      graphql.pages.create(draft, from: template_id).tap do |result|
+        @created_pages += 1 if result.respond_to?(:page_id) && result.page_id
+      end
+    end
+
+    # Cursor-paginated iteration over the register's pages. Counts total search
+    # results and flags duplicated page ids (dedup-by-id, v2 parity).
+    def each_page(conf: search_conf, first: self.class.batch_size)
+      graphql.pages.each(search_conf: conf.to_h, first: first) do |page|
+        @total_search_pages += 1
+        if page_result_ids[page.id]
+          @dupped_search_pages += 1
+        else
+          page_result_ids[page.id] = true
+          @total_pages += 1
+        end
+        @retrieved_pages += 1
+        yield page
+      end
+    end
+
+    private
+
+    # Dry-run preview of what a create WOULD send. Faithful but scoped: the
+    # GraphQL cursor search offers no cheap "total before filtering" count like the
+    # v2 registers.search(only_first:), so there is no up-front count prompt here.
+    def dry_run_feedback(draft)
+      log(:info) { "Simulate — would create page from template #{draft&.template_id}" }
+      nil
+    end
+
+    def results_preview
+      log(:info) { "Processing register '#{register_id}' in batches of #{self.class.batch_size}" }
+    end
+
+    def init_kpis
+      super
+      @total_search_pages   = 0
+      @dupped_search_pages  = 0
+      @retrieved_pages      = 0
+      @page_result_ids      = {}
+      @created_pages        = 0
+      @page_create_attempts = 0
+    end
+
+    def kpis_message
+      [
+        'Run end:',
+        "  * Search results:  #{total_search_pages}",
+        "  * Duplicated:      #{dupped_search_pages}",
+        "  * Retrieved:       #{retrieved_pages}",
+        "  * Processed:       #{processed_pages}",
+        "  * Updated:         #{updated_pages} (of #{total_pages} unique)",
+        "  * Created:         #{created_pages} (of #{page_create_attempts} attempts)",
+        "  * Skipped:         #{skipped_pages}",
+        "  * Failed:          #{failed_pages}"
+      ].join("\n")
+    end
+  end
+end

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

@@ -0,0 +1,132 @@
+module Eco::API::UseCases::GraphQL::Samples::Pages
+  # Native GraphQL re-expression of OozeSamples::RegisterMigrationCase.
+  #
+  # Migrates the entries of a register into NEW entries of a (possibly different)
+  # template, copying data across by PAIRING typed fields between the source page
+  # and the freshly drafted destination page. Field pairing is delegated to the
+  # native `Helpers::Pages::TypedFieldsPairing` (label + type matching over
+  # GraphQL DataField types); the actual per-field content copy dispatches on the
+  # GraphQL DataField TYPE STRING (mirroring how OozeHandlers#merge_values ports
+  # the v2 type-class dispatch).
+  #
+  # It reproduces the SHAPE of RegisterMigrationCase natively:
+  #   * iterate the source register (inherited from Register::Base#each_page)
+  #   * draft a new entry of TEMPLATE_ID (via the native Creatable)
+  #   * pair the source fields to the draft fields and copy content
+  #   * run the unpaired / multi-pair reports (data-loss visibility)
+  #   * let a subclass finalise the draft via #custom_processing
+  #
+  # As with the rest of the native samples layer this is NON-BREAKING and
+  # additive: no OozeSamples name is flipped and the legacy
+  # HelpersMigration::TypedFieldsPairing / RegisterMigrationCase are untouched.
+  #
+  # == What differs from the v2 case
+  # * dispatch is on GraphQL DataField type strings (PlainText/Select/...) not
+  #   V2 component classes / snake_case types
+  # * the per-page persistence is the native create path (Creatable#create_ooze →
+  #   graphql.pages.create), not the v2 batch queue
+  # * the v2 JSON `field_maps` / `copy_hooked_fields` mapping layer is NOT ported
+  #   here (that consumes the v2 `with_fields`/regex-hook helpers); this scaffold
+  #   covers the generic typed pairing. Mapped-field hooks are a later increment.
+  #
+  # == Subclass interface
+  #
+  #   class Custom::UseCase::MigrateTraining < Eco::API::UseCases::GraphQL::Samples::Pages::Register::MigrationCase
+  #     name 'migrate-training'
+  #     register_id 'REG_SOURCE'   # source register to read from
+  #     TEMPLATE_ID = 'TPL_DEST'   # destination template to create entries of
+  #
+  #     # Optional: finalise the draft after generic pairing has run.
+  #     def custom_processing(draft, source, fields_tracker: nil)
+  #       draft.name = source.name
+  #     end
+  #   end
+  #
+  # Expects `options[:source][:register_id]` (or class `register_id`) for the
+  # source scope, and a destination template id via the `TEMPLATE_ID` constant
+  # (overridable through #destination_template_id).
+  class Register::MigrationCase < Register::Base
+    include Eco::API::UseCases::GraphQL::Helpers::Pages::Copying
+
+    name 'graphql-register-migration-case'
+    type :other
+
+    # Destination template constant (subclasses set this).
+    TEMPLATE_ID = nil
+
+    # whether or not it should try to pair src <-> dst ximport fields
+    EXCLUDE_XIMPORT = false
+    # whether or not it should warn on unpaired destination ximport fields
+    REPORT_DST_XIMPORT = true
+    # whether or not it should warn on unpaired source fields that are empty (no data loss)
+    REPORT_SRC_EMPTY = false
+    # whether or not it should warn on unpaired source fields that are deindexed
+    REPORT_SRC_DEINDEX = false
+
+    # One source entry → one new destination entry.
+    #
+    # Drafts a destination page of `destination_template_id`, pairs the source
+    # fields to the draft's fields, copies content across, runs the reports, and
+    # (optionally) hands the draft to #custom_processing for finalising.
+    def process_page(source)
+      draft_reference = object_reference(source)
+      creating_new_page(draft_reference, template_id: destination_template_id) do |draft|
+        pairing_tracking = copy_pairings(source, draft)
+
+        if respond_to?(:custom_processing, true)
+          custom_processing(draft, source, fields_tracker: pairing_tracking)
+        elsif block_given?
+          yield(draft, source, fields_tracker: pairing_tracking)
+        end
+
+        report_pairing(pairing_tracking)
+      end
+    end
+
+    protected
+
+    # The destination template to create entries of. Override or set TEMPLATE_ID.
+    def destination_template_id
+      tpl = self.class::TEMPLATE_ID
+      raise ArgumentError, "No destination template configured (set #{self.class}::TEMPLATE_ID)" unless tpl
+
+      tpl
+    end
+
+    private
+
+    # Pair the generic typed fields and copy their content. Returns the tracker so
+    # the caller can inspect unpaired / multi-paired fields.
+    def copy_pairings(src, dst)
+      after_copy = respond_to?(:paired_fields_post_callback, true) ? method(:paired_fields_post_callback) : nil
+
+      copy_generic_paired_fields(
+        src,
+        dst,
+        exclude_ximport: self.class::EXCLUDE_XIMPORT,
+        &after_copy
+      )
+    end
+
+    def report_pairing(tracker)
+      msg = tracker.report_src_unpaired(
+        only_present: !self.class::REPORT_SRC_EMPTY,
+        only_indexed: !self.class::REPORT_SRC_DEINDEX
+      )
+      log(:warn) { msg } if msg
+
+      msg = tracker.report_multi_pairs(
+        only_present:        !self.class::REPORT_SRC_EMPTY,
+        only_indexed:        !self.class::REPORT_SRC_DEINDEX,
+        dst_exclude_ximport: !self.class::REPORT_DST_XIMPORT
+      )
+      log(:warn) { msg } if msg
+
+      msg = tracker.report_dst_unpaired(
+        only_required:   false,
+        exclude_ximport: !self.class::REPORT_DST_XIMPORT
+      )
+      log(:warn) { msg } if msg
+    end
+  end
+end

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