eco-helpers 3.2.14 → 3.2.16

data/lib/eco/api/usecases/graphql/compat/ooze_redirect/field_patches.rb

@@ -0,0 +1,241 @@
+module Eco::API::UseCases::GraphQL::Compat::OozeRedirect
+  # Applies one-time compatibility patches to v2 and GraphQL field classes.
+  # Idempotent — safe to call multiple times (first call does the work, rest no-op).
+  #
+  # After apply!:
+  #   1. V2 type classes recognise GraphQL instances in case/when dispatch
+  #   2. GraphQL field classes respond to the v2 field interface
+  module FieldPatches
+    @applied = false
+
+    V2_TO_GQL = {
+      'PlainTextField'   => 'PlainText',
+      'NumberField'      => 'Number',
+      'SelectionField'   => 'Select',
+      'PeopleField'      => 'People',
+      'ReferenceField'   => 'CrossReference'
+    }.freeze
+
+    def self.apply!
+      return if @applied
+
+      # eco-helpers lazy-requires the gem only when session.api(version: :graphql) is first
+      # used (runtime). apply! runs at OozeRedirect.included (boot) — BEFORE that — so the
+      # gem classes aren't loaded yet: every safe_const below would return nil, the patches
+      # would silently no-op, and @applied would latch with nothing patched. Force the gem
+      # load now so all the GraphQL consts resolve.
+      require 'ecoportal/api-graphql'
+
+      @applied = true
+      patch_v2_type_dispatch!
+      patch_graphql_base_field!
+      patch_graphql_people!
+      patch_graphql_cross_reference!
+      patch_graphql_select!
+    end
+
+    # --- 1. V2 type dispatch -------------------------------------------------
+
+    # Reopen each V2 field class so that `===` also returns true for the
+    # equivalent GraphQL field type.  This makes existing `case/when` dispatch
+    # work transparently without touching the end scripts.
+    def self.patch_v2_type_dispatch!
+      V2_TO_GQL.each do |v2_type, gql_type|
+        v2_klass  = safe_const("Ecoportal::API::V2::Page::Component::#{v2_type}")
+        gql_klass = safe_const("Ecoportal::API::GraphQL::Base::Page::DataField::#{gql_type}")
+        next unless v2_klass && gql_klass
+
+        gql_ref = gql_klass   # capture for the closures
+        v2_ref  = v2_klass
+
+        # case/when dispatch: `V2Class === graphql_instance`.
+        v2_klass.define_singleton_method(:===) do |obj|
+          super(obj) || obj.is_a?(gql_ref)
+        end
+
+        # is_a?/kind_of? guards: `graphql_instance.is_a?(V2Class)` — scripts use both the
+        # case/when form AND explicit is_a? guards (e.g. cans update_select). === alone
+        # doesn't cover is_a?, so make the GraphQL field recognise its v2 counterpart too.
+        gql_klass.prepend(Module.new do
+          define_method(:is_a?)    { |klass| klass == v2_ref || super(klass) }
+          define_method(:kind_of?) { |klass| klass == v2_ref || super(klass) }
+        end)
+      end
+    end
+
+    # --- 2. GraphQL base field: submit! + ooze stub --------------------------
+
+    def self.patch_graphql_base_field!
+      base = safe_const('Ecoportal::API::GraphQL::Base::Page::DataField')
+      return unless base
+
+      # submit! — stores a pending submit flag consumed by the infrastructure
+      base.class_eval do
+        def _compat_submit_pending?
+          @_v2_compat_submit_pending
+        end
+      end
+
+      # BasePage submit! — called as target.submit!(force: true) in scripts
+      page_base = safe_const('Ecoportal::API::GraphQL::Interface::BasePage')
+      return unless page_base
+
+      page_base.class_eval do
+        # v2-compat stage SUBMIT. Scripts call `target.submit!` (optionally pinning a
+        # stage via `submit!(stage_id:)`). Captures the intent; OozeRedirect#process_ooze
+        # consumes it → `graphql.pages.update(submit: true)`. Submitting completes the
+        # stage's fill-in task (the server requires all visible, non-hidden required
+        # fields to be filled). If the stage also has a review task configured, it then
+        # awaits a SEPARATE `sign_off!`. submit! does NOT sign off.
+        #
+        # `submit!(force: true)` maps to completePageTask.forcedComplete: true — the
+        # backend then SKIPS the empty visible-required-field check. This is admin/
+        # superuser-only server-side; the integration's service user must hold that
+        # permission (it did under APIv2, so the same account carries it on GraphQL).
+        def submit!(force: false, stage_id: nil)
+          @_v2_compat_submit_pending  = true
+          @_v2_compat_submit_stage_id = stage_id
+          @_v2_compat_submit_force    = force ? true : false
+        end
+
+        # v2-compat stage SIGN-OFF. Scripts call `target.sign_off!` (optionally
+        # `sign_off!(stage_id:)`). Per the platform model the stage tasks are sequential
+        # (fill-in → review): signing off a stage that has NOT been submitted yet also
+        # submits it — a permitted user may submit + sign off in one go (also the page-
+        # creation path). process_ooze realises this as
+        # `updatePage(submit: true, completePageTask { signOff: true })`, which the
+        # backend treats as submit + inline review approval, advancing the stage.
+        def sign_off!(stage_id: nil)
+          @_v2_compat_sign_off_pending  = true
+          @_v2_compat_sign_off_stage_id = stage_id
+        end
+
+        def _compat_submit?
+          @_v2_compat_submit_pending
+        end
+
+        def _compat_submit_stage_id
+          @_v2_compat_submit_stage_id
+        end
+
+        def _compat_submit_force?
+          @_v2_compat_submit_force ? true : false
+        end
+
+        def _compat_sign_off?
+          @_v2_compat_sign_off_pending
+        end
+
+        def _compat_sign_off_stage_id
+          @_v2_compat_sign_off_stage_id
+        end
+      end
+    end
+
+    # --- 3. People field -----------------------------------------------------
+
+    def self.patch_graphql_people!
+      klass = safe_const('Ecoportal::API::GraphQL::Base::Page::DataField::People')
+      return unless klass
+
+      klass.prepend(Module.new do
+        # Return a DirtyArray so fld.people_ids << value triggers dirty tracking
+        def people_ids
+          DirtyArray.new(self, Array(super))
+        end
+
+        # Stub: back-reference used in v2 warning messages
+        def ooze
+          Struct.new(:uid, :name, :id).new('(graphql)', label, id)
+        end
+      end)
+    end
+
+    # --- 4. CrossReference (v2 ReferenceField) field -------------------------
+
+    def self.patch_graphql_cross_reference!
+      klass = safe_const('Ecoportal::API::GraphQL::Base::Page::DataField::CrossReference')
+      return unless klass
+
+      klass.prepend(Module.new do
+        # v2 compat: fld.reference_ids → fld.page_ids
+        def reference_ids
+          page_ids || []
+        end
+
+        # v2 compat: fld.add(ep_id)
+        def add(ep_id)
+          return if ep_id.nil?
+
+          self.page_ids = (page_ids || []) + [ep_id] unless (page_ids || []).include?(ep_id)
+        end
+
+        # v2 compat: fld.clear
+        def clear
+          self.page_ids = []
+        end
+
+        def ooze
+          Struct.new(:uid, :name, :id).new('(graphql)', label, id)
+        end
+      end)
+    end
+
+    # --- 5. Select field -----------------------------------------------------
+
+    OptionStruct = Struct.new(:id, :name, :value, :selected)
+
+    def self.patch_graphql_select!
+      klass = safe_const('Ecoportal::API::GraphQL::Base::Page::DataField::Select')
+      return unless klass
+
+      klass.prepend(Module.new do
+        # v2 compat: fld.options → array of OptionStructs (respond to .name, .value)
+        def options
+          Array(doc['options'] || []).map do |opt|
+            FieldPatches::OptionStruct.new(opt['id'], opt['name'], opt['value'], opt['selected'])
+          end
+        end
+
+        # v2 compat: fld.select(value, by_name: false) or fld.select(name, by_name: true)
+        def select(val, by_name: false)
+          select_option(val.to_s)
+          self
+        end
+
+        # v2 compat: fld.deselect(value) — deselect one specific option
+        def deselect(val)
+          (doc['options'] || []).each do |opt|
+            target = val.to_s
+            if [opt['id'], opt['name'], opt['value']].map(&:to_s).include?(target)
+              opt['selected'] = false
+            end
+          end
+          # No explicit dirty call: mutating doc['options'] in place is picked up
+          # by DataField's LeafDiffService diff (same as native select_option /
+          # clear_selection). There is no mark_dirty! method on the field.
+          self
+        end
+
+        # v2 compat: fld.values — array of selected option values
+        def values
+          (doc['options'] || []).select { |opt| opt['selected'] }.map { |opt| opt['value'] }
+        end
+
+        def ooze
+          Struct.new(:uid, :name, :id).new('(graphql)', label, id)
+        end
+      end)
+    end
+
+    def self.safe_const(path)
+      path.split('::').reduce(Object) { |mod, c| mod.const_get(c) }
+    rescue NameError
+      nil
+    end
+
+    private_class_method :patch_v2_type_dispatch!, :patch_graphql_base_field!,
+                         :patch_graphql_people!, :patch_graphql_cross_reference!,
+                         :patch_graphql_select!, :safe_const
+  end
+end

data/lib/eco/api/usecases/graphql/compat/ooze_redirect/force_compat.rb

@@ -0,0 +1,73 @@
+module Eco::API::UseCases::GraphQL::Compat::OozeRedirect
+  # Extends OozeRedirect with Force / binding support via the GraphQL
+  # executeWorkflowCommands mutation.
+  #
+  # Automatically included by OozeRedirect when the ForceFields fragment is
+  # available in the loaded gem version.  No additional include is needed in
+  # end scripts — the same single include covers forces too:
+  #
+  #   include Eco::API::UseCases::GraphQL::Compat::OozeRedirect
+  #
+  # ## What ForceCompat adds
+  #
+  # 1. Override `with_each_entry` to fetch pages via Query::PageWithForces,
+  #    which includes forces in the GraphQL response.
+  # 2. Override `process_ooze` to call save_force_changes! after the script
+  #    runs, executing any accumulated force commands via executeWorkflowCommands.
+  #
+  # ## Accumulated commands
+  #
+  # Scripts interact with forces exactly as in v2:
+  #   force.custom_script = new_script       # queues editForce
+  #   force.bindings.add(field, name: 'n')   # queues addBinding
+  #   force.bindings.delete!(binding)        # queues removeBinding
+  #
+  # After process_ooze returns, ForceCompat collects all pending commands from
+  # all forces on the page and submits them in one executeWorkflowCommands call.
+  module ForceCompat
+    module Infrastructure
+      # Fetch pages with forces included in the GraphQL response.
+      def with_each_entry
+        warn_once(:force_fetch, 'ForceCompat: fetching pages with forces (Query::PageWithForces)')
+        target_ids.each do |page_id|
+          @target = Ecoportal::API::GraphQL::Query::PageWithForces.new(graphql.client).query(id: page_id)
+          if @target
+            yield
+          else
+            log(:warn) { "[ForceCompat] Could not fetch page #{page_id}" }
+          end
+        end
+      end
+
+      # After the script's process_ooze runs, submit all accumulated force commands.
+      def process_ooze
+        super
+        save_force_changes!
+      end
+
+      private
+
+      def save_force_changes!
+        return unless target.respond_to?(:forces)
+
+        force_col = target.forces
+        return unless force_col.dirty?
+
+        commands = force_col.pending_commands
+        return if commands.empty?
+
+        warn_once(:force_save, "ForceCompat: executing #{commands.size} force command(s) via executeWorkflowCommands")
+        return if simulate?
+
+        response = graphql.page.execute_force_commands(
+          id:        target.id,
+          patch_ver: target.patchVer.to_i,
+          commands:  commands
+        )
+        if response.respond_to?(:error?) && response.error?
+          log(:error) { "[ForceCompat] executeWorkflowCommands failed for page #{target.id}: #{response.body}" }
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/usecases/graphql/compat/ooze_redirect.rb

@@ -0,0 +1,234 @@
+module Eco::API::UseCases::GraphQL::Compat
+  # Transparently redirects an OozeSamples-based use case from the APIv2 ooze
+  # path to the GraphQL compat layer.  Include it in the case class and nothing
+  # else needs to change in the script.
+  #
+  # ## What it redirects
+  #
+  # - Page iteration: `with_each_entry` fetches via `graphql.pages.get`
+  # - `api_v2` / `apiv2`: returns the graphql compat client
+  # - `stage(name)`: resolves via `target.stages[name]` (GraphQL stage model)
+  # - `with_fields(ooz, label:, type:)`: reads from `ooz.components` (GraphQL)
+  # - `update_ooze(ooz)`: saves via `graphql.pages.update`
+  # - `target.submit!` / `target.sign_off!`: captured and forwarded to `graphql.pages.update`
+  #
+  # ## What it patches (one-time, guarded)
+  #
+  # - V2 type classes (`PlainTextField`, `SelectionField`, etc.) recognise
+  #   GraphQL instances in `case/when` dispatch via `===`
+  # - GraphQL `People` field: `people_ids <<` triggers dirty tracking
+  # - GraphQL `CrossReference` field: `add`, `clear`, `reference_ids`
+  # - GraphQL `Select` field: `select`, `deselect`, `values`, `options`
+  #   (options returns Struct objects with `.name` / `.value`)
+  # - All GraphQL fields: `ooze` stub returns a minimal object for warning messages
+  # - `Interface::BasePage`: `submit!(stage_id:)` queues a submit-only flag (completes
+  #   the fill-in task); `sign_off!(stage_id:)` queues sign-off. Tasks are sequential
+  #   (fill-in → review): sign-off on a not-yet-submitted stage submits + signs off in
+  #   one go (completePageTask{ signOff: true }). `submit!(force: true)` maps to
+  #   completePageTask{ forcedComplete: true } (admin/superuser; skips the required-field check).
+  #
+  # ## Per-run debug logging
+  #
+  # Each type of redirection logs once per run (not per page) at `:debug` level.
+  # Filter with `ECOPORTAL_LOG_LEVEL=debug` or the session logger config.
+  #
+  # ## Usage
+  #
+  #   class Custom::UseCase::TOOCSCoding < Eco::API::UseCases::OozeSamples::TargetOozesUpdateCase
+  #     include Eco::API::UseCases::GraphQL::Compat::OozeRedirect
+  #     # ... rest of class unchanged ...
+  #   end
+  #
+  # ## Limitations
+  #
+  # - Force / binding operations (`target.forces`, `force.bindings`) are not
+  #   available in GraphQL — those calls will raise NoMethodError.
+  # - Field property setters (`fld.label=`, `fld.required=`) are template
+  #   mutations; they are not supported and will raise NoMethodError.
+  # - `page_result.membranes` (on PreviewPage search results) is not supported
+  #   directly; use register search via `graphql.registers.search` instead.
+  #
+  # ## TODO: Force / binding support (blocked on GraphQL endpoint)
+  #
+  # Engineering is working on exposing "legacy forces" via the GraphQL API.
+  # Once that endpoint is available, extend this module with a `ForceCompat`
+  # sub-module (same include pattern — nothing changes in end scripts) covering:
+  #
+  #   target.forces.get_by_name(name)      → query forces by name on a page
+  #   force.bindings.get_by_name(name)     → field bindings on a force
+  #   force.bindings.add(field, name:)     → add a binding
+  #   force.bindings.delete!(binding)      → remove a binding
+  #   force.custom_script                  → read the LISP script
+  #   force.custom_script = new_script     → write the LISP script
+  #   force.script                         → raw script content (alias)
+  #
+  # Affected cases currently blocked (from multi_org_api survey, ~50% of all
+  # ooze cases):
+  #   act-gov:        5 x 20240130_act_*_case, rearrage_page_sites_case
+  #   briscoes:       remove_induction_sections, 310524_Briscoes_Remove_Tasks
+  #   chorus:         4 x audit_update cases
+  #   hcc:            update_enterprise_risk_case
+  #   lic:            update_life_cycle_force_case
+  #   mitre10:        rich_text_update, update_location_force, updating_template
+  #   npdc:           contractor_title_force, risk_titile_force, fix_title_syncing,
+  #                   reminder_date_fields, 10092024_NPDC_CP_Add_Force
+  #   profile-group:  int_training_review, 20231026_profile_wellness
+  #   turners-growers: event_changes, inj_cost_calc, remove_line_force
+  #   twg:            hide_attached_risks, add_new_force
+  #
+  # Implementation sketch (to be built when the endpoint lands):
+  #
+  #   module ForceCompat
+  #     # Patch GraphQL BasePage to respond to .forces
+  #     # Returns a proxy whose #get_by_name queries the GraphQL force endpoint
+  #     # and returns ForceProxy objects wrapping the response.
+  #     # ForceProxy exposes #bindings (BindingsProxy), #custom_script, #script.
+  #     # BindingsProxy exposes #get_by_name, #add, #delete!.
+  #   end
+  #
+  #   OozeRedirect.include(ForceCompat)  # or extend OozeRedirect::FieldPatches
+  module OozeRedirect
+    require_relative 'ooze_redirect/dirty_array'
+    require_relative 'ooze_redirect/field_patches'
+    require_relative 'ooze_redirect/force_compat'
+
+    def self.included(base)
+      FieldPatches.apply!
+      # Provide `graphql` (lazy, memoized session.api(version: :graphql)) regardless of
+      # the host's base class. OozeSamples cases (cans/toocs) don't include the GraphQL
+      # helpers that Custom::UseCase paths pick up, yet Infrastructure#api_v2 /
+      # #with_each_entry / #update_ooze all call `graphql` — without this they raise
+      # NameError: undefined `graphql`.
+      base.include(Eco::API::UseCases::GraphQL::Helpers::Base::GraphQLEnv)
+      # Prepend Infrastructure first so it sits below ForceCompat in the MRO.
+      # With Ruby's prepend, last-prepended wins — so ForceCompat::Infrastructure
+      # must be prepended AFTER Infrastructure to be first in the lookup chain:
+      #   MRO: ForceCompat::Infrastructure → Infrastructure → base class
+      base.prepend(Infrastructure)
+      base.prepend(ForceCompat::Infrastructure) if force_support?
+    end
+
+    # Returns true when the installed ecoportal-api-graphql gem exposes
+    # Query::PageWithForces (the forces-aware page query).
+    # Forces are NOT usable on GraphQL yet: Query::PageWithForces is a WIP whose query
+    # currently fails schema validation (selections on PageUnion; `id` on DataFieldBinding/
+    # SectionBinding; unused ForceFields) and the backend forces endpoint is still in
+    # progress. The class merely being *defined* is not a readiness signal — activating
+    # ForceCompat on that basis makes EVERY OozeRedirect case fetch via the broken force
+    # query (e.g. toocs, which doesn't even use forces). Keep OFF until forces actually
+    # work; then restore a real readiness check.
+    def self.force_support?
+      false
+    end
+
+    # Method overrides that replace the v2 infrastructure with GraphQL calls.
+    # Prepended onto the including class so they take priority over inherited methods.
+    module Infrastructure
+      # NOTE: with_each_entry / update_ooze / process_ooze are intentionally NOT overridden.
+      # The base OozeSamples loop (RegisterUpdateCase / TargetOozesUpdateCase) already does the
+      # right thing once api_v2 is redirected to GraphQL: it counts KPIs (search/retrieved/
+      # updated/created), dedups, queues, and — crucially — runs dry_run_feedback in simulate
+      # to PRINT the pending diff. Fetches go through ooze(id) → apiv2.pages.get (redirected
+      # below), and saves go through update_oozes → update_ooze → apiv2.pages.update. A captured
+      # target.submit!/sign_off! rides along on that single update via Input::Page::Update
+      # .from_model (it reads the page's _compat_* flags). Overriding the loop here is what
+      # silently dropped all of that — don't reintroduce it.
+
+      # --- API client redirect ------------------------------------------------
+
+      # Return the GraphQL compat client in place of the v2 client.
+      # Handles direct api_v2.pages.* calls in scripts that don't use OozeSamples
+      # iteration (e.g. get_new, create, update called directly).
+      def api_v2
+        warn_once(:api_v2, 'api_v2 → graphql compat layer')
+        graphql
+      end
+
+      alias apiv2 api_v2
+
+      # --- Stage access -------------------------------------------------------
+
+      # Resolve a stage by name from the current GraphQL page.
+      # Replaces the v2 stage fetch from OozeBaseCase.
+      def stage(id_name, ooze: target)
+        warn_once(:stage, "stage('#{id_name}') → StageView over target.stages[name]")
+        stg = ooze.stages[id_name.to_s]
+        return nil unless stg
+
+        # Return a StageView (v2 "page-at-a-stage" semantics): #id / #name / #state /
+        # #submit! / #as_update / #dirty? delegate to the PAGE, while #components and
+        # #sections are scoped to this stage. Scripts rely on stage.id == page.id
+        # (e.g. with_row(stage.id), keyed by page id); the raw Base::Page::Phased::Stage#id
+        # is the STAGE's own id and breaks that. Field objects stay the page's canonical
+        # ones, so mutations via stage.components still reach pages.update.
+        Ecoportal::API::GraphQL::Compat::StageView.new(ooze, stg.id)
+      rescue NoMethodError
+        log(:warn) { "[OozeRedirect] stages not available on #{ooze.class}" }
+        nil
+      end
+
+      # --- Field access -------------------------------------------------------
+
+      # Redirect field lookups from v2 component access to GraphQL components.
+      # Supports the same type: and label: keyword arguments.
+      def with_fields(ooz = target, type: nil, label: nil) # rubocop:disable Metrics/MethodLength
+        warn_once(:with_fields, 'with_fields → ooz.components (GraphQL)')
+        collection = ooz.respond_to?(:components) ? ooz.components : nil
+
+        unless collection
+          log(:warn) { "[OozeRedirect] No components on #{ooz.class}" }
+          return []
+        end
+
+        if label && type
+          field = collection.get_by_name(label)
+          field && type_match?(field, type) ? [field] : []
+        elsif label
+          [collection.get_by_name(label)].compact
+        elsif type
+          collection.get_by_type(type)
+        else
+          collection.to_a
+        end
+      end
+
+      # --- Dirty check --------------------------------------------------------
+
+      # v2 dirty?(ooze) reads patch_doc(ooze)['page']; the GraphQL compat get_body wraps the
+      # model's as_update under 'page' (nil when unchanged), so the base dirty? works too —
+      # but delegate to the model's real #dirty? for clarity AND treat a captured submit!/
+      # sign_off! as dirty, so the base update_ooze still fires for a page that only needs
+      # submitting (no field changes). The submit/sign-off itself is carried on that single
+      # update by Input::Page::Update.from_model (reads the _compat_* flags).
+      def dirty?(object)
+        return false unless object
+
+        pending = (object.respond_to?(:_compat_submit?)   && object._compat_submit?) ||
+                  (object.respond_to?(:_compat_sign_off?) && object._compat_sign_off?)
+        return true if pending
+        return object.dirty? if object.respond_to?(:dirty?)
+
+        super
+      end
+
+      private
+
+      # Log a debug message exactly once per use-case run per operation type.
+      def warn_once(op_key, message)
+        @_warned_ops ||= Set.new
+        return if @_warned_ops.include?(op_key)
+
+        @_warned_ops << op_key
+        log(:debug) { "[OozeRedirect] #{message}" }
+      end
+
+      # Check whether a GraphQL field matches a v2-style type string.
+      # v2 uses e.g. "select", "people", "cross_reference"; normalise both sides.
+      def type_match?(field, type_key)
+        target_norm = type_key.to_s.downcase.delete('_')
+        field_norm  = field.type.to_s.downcase.delete('_')
+        target_norm == field_norm
+      end
+    end
+  end
+end

data/lib/eco/api/usecases/graphql/compat.rb

@@ -0,0 +1,6 @@
+module Eco::API::UseCases::GraphQL
+  module Compat
+  end
+end
+
+require_relative 'compat/ooze_redirect'

data/lib/eco/api/usecases/graphql/helpers/CLAUDE.md

@@ -0,0 +1,79 @@
+# usecases/graphql/helpers
+
+Mixin modules providing domain-specific helper methods for GraphQL use cases.
+All modules are ultimately included via `Helpers::Base` into `GraphQL::Base`.
+
+---
+
+## Include chain
+
+```
+GraphQL::Base
+    includes Helpers::Base
+        includes CaseEnv        → session, options, config, simulate?, log, ErrorHandling
+        includes GraphQLEnv     → graphql (lazy, memoized)
+    includes Helpers (loader)
+        includes Helpers::Location      → location tree helpers
+        includes Helpers::Contractors   → contractor entity helpers
+```
+
+---
+
+## Helpers::Base (`helpers/base.rb`)
+
+Core environment — included in every GraphQL use case.
+
+| Method | Source | Description |
+|--------|--------|-------------|
+| `session` | `CaseEnv` | Current `Eco::API::Session` |
+| `options` | `CaseEnv` | Options hash from CLI/runner |
+| `config` | `CaseEnv` | `session.config` shortcut |
+| `simulate?` | `CaseEnv` | `options[:simulate] \|\| options[:dry_run]` |
+| `log(level)` | `CaseEnv` | Logger proxy |
+| `graphql` | `GraphQLEnv` | Lazy-loaded `Ecoportal::API::GraphQL` instance |
+| `backup(data, type:)` | `Helpers::Base` | Save JSON to requests folder |
+| `exit_error(msg)` | `Helpers::Base` | Log error and `exit(1)` |
+
+---
+
+## Helpers::Location (`helpers/location/`)
+
+Location tree access, tag remapping, classification parsing.
+
+- `helpers/location/base.rb` — `Location::Base` mixin
+- `helpers/location/base/tree_tracking.rb` — track tree mutations
+- `helpers/location/base/classifications_parser.rb` — parse location classifications
+- `helpers/location/tags_remap/` — remapping tags across location changes
+- `helpers/location/command/` — apply/diff location structure commands
+
+---
+
+## Helpers::Contractors (`helpers/contractors/`)
+
+Contractor entity loading helpers.
+
+- `helpers/contractors/base.rb` — base contractor helpers
+- `helpers/contractors/base/load.rb` — batch load contractor entities
+
+---
+
+## Adding a new helper
+
+1. Create `helpers/my_domain/base.rb`:
+   ```ruby
+   module Eco::API::UseCases::GraphQL::Helpers
+     module MyDomain
+       module Base
+         private
+         def my_helper_method
+           graphql.myDomainQuery(...)
+         end
+       end
+     end
+   end
+   ```
+2. Create `helpers/my_domain.rb` as a loader that includes `Base`
+3. Add `require_relative 'my_domain'` to `helpers.rb`
+
+The helper is then available in all cases that include `Helpers::Base` (i.e., all
+subclasses of `GraphQL::Base` including `PageCase` and `OrgPageCase`).