eco-helpers 3.2.14 → 3.2.16

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

@@ -0,0 +1,76 @@
+# usecases/graphql/samples
+
+Built-in GraphQL sample base classes shipped with the gem.
+These are abstract/semi-abstract classes that org scripts inherit from.
+Concrete, CLI-integrated cases go in `usecases/default/` instead.
+
+---
+
+## Hierarchy convention
+
+Each domain follows:
+```
+samples/<domain>.rb              ← namespace loader (may also BE the base class)
+samples/<domain>/
+  <level>/
+    dsl.rb                       ← DSL concern — include in base, available to subclasses
+    base.rb                      ← Base class (inherits from GraphQL::Base or parent level)
+    <functional_level>.rb        ← Optional: opinionated subclass, inherit directly
+    <functional_level>/
+      dsl.rb                     ← Further DSL for that functional level
+```
+
+DSLs are always **concerns (modules)** to include — never classes.
+Bases are **classes** with the scaffolding logic.
+Functional levels add opinionated defaults on top of base.
+
+---
+
+## Contents
+
+| File | Class | Purpose |
+|------|-------|---------|
+| `samples/location.rb` | `Samples::Location` | Location structure management |
+| `samples/location/command.rb` | `Samples::Location::Command` | Apply location tree commands |
+| `samples/location/service.rb` | `Samples::Location::Service` | Tree diffing and conversion service |
+| `samples/contractors.rb` | `Samples::Contractors` | Contractor entity base case |
+| `samples/contractors/dsl.rb` | `Contractors::DSL` | Contractor helper mixin |
+| `samples/pages.rb` | `Samples::Pages` (namespace) | Page processing cases loader |
+| `samples/pages/page/dsl.rb` | `Pages::Page::DSL` | SearchConf helpers mixin |
+| `samples/pages/page/base.rb` | `Pages::Page::Base` | Register-scoped page iteration |
+| `samples/pages/org_page/dsl.rb` | `Pages::OrgPage::DSL` | Org-page DSL (extends Page::DSL) |
+| `samples/pages/org_page/base.rb` | `Pages::OrgPage::Base` | Org-wide page iteration |
+
+---
+
+## Difference: samples vs org-specific cases vs default
+
+| Layer | Location | Purpose |
+|---|---|---|
+| **samples** (here) | `eco-helpers/lib/.../graphql/samples/` | Abstract base classes — org scripts inherit |
+| **default** | `eco-helpers/lib/.../usecases/default/` | Concrete CLI-integrated cases for ALL orgs |
+| **org-specific** | `multi_org_api/{org}/config/graphql_cases/` | Org-specific implementations |
+
+Org scripts inherit from `samples/`, optionally via `default/` as an intermediate layer.
+
+---
+
+## Adding a new built-in sample
+
+1. Create the case file in `samples/`:
+   ```ruby
+   # lib/eco/api/usecases/graphql/samples/my_domain.rb
+   class Eco::API::UseCases::GraphQL::Samples::MyDomain < Eco::API::UseCases::GraphQL::Base
+     name 'my-domain-case'
+     type :other
+
+     def process
+       # ...
+     end
+   end
+   ```
+
+2. Add `require_relative 'samples/my_domain'` to `samples.rb`.
+
+If the case is page-centric, inherit from `PageCase` instead of `Base` to get
+pagination, KPI tracking, and `update_page` for free.

data/lib/eco/api/usecases/graphql/samples/pages/CLAUDE.md

@@ -0,0 +1,59 @@
+# samples/pages
+
+Base classes for GraphQL-native page processing use cases.
+
+---
+
+## Structure
+
+```
+pages/
+  page/
+    dsl.rb          ← Page::DSL — SearchConf helpers mixin (sc, in_register, state_is, ...)
+    base.rb         ← Page::Base — register-scoped page iteration + KPI scaffolding
+  org_page/
+    dsl.rb          ← OrgPage::DSL — extends Page::DSL (org-wide helpers)
+    base.rb         ← OrgPage::Base — org-wide iteration (no default register scope)
+```
+
+---
+
+## Inheritance
+
+```
+GraphQL::Base
+    ↓
+Samples::Pages::Page::Base          (register-scoped, inherits Page::DSL)
+    ↓
+Samples::Pages::OrgPage::Base       (org-wide, overrides search_conf)
+    ↓
+your org subclass
+```
+
+---
+
+## Page::Base — register-scoped scripts
+
+Override `process_page(page)` and optionally `search_conf`.
+Set `register_id` and `batch_size` on the class.
+
+## OrgPage::Base — org-wide scripts
+
+Same as Page::Base but `search_conf` starts empty.
+Add your own filters via `super.filter(state_is(:active))` etc.
+
+---
+
+## Adding a functional level
+
+If a common pattern emerges (e.g., "stage-submit scripts"), add:
+
+```
+pages/page/
+  stage_submitter.rb          ← Page::StageSubmitter < Page::Base
+  stage_submitter/
+    dsl.rb                    ← StageSubmitter::DSL
+```
+
+Keep base.rb for the pure iteration scaffolding; put opinionated defaults in
+the functional level so scripts can choose their entry point.

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

@@ -0,0 +1,41 @@
+module Eco::API::UseCases::GraphQL::Samples::Pages
+  # Base class for **org-wide** page processing use cases.
+  #
+  # Identical to Page::Base but with no default register scope — search_conf
+  # starts empty (all org pages). Subclass adds filters via super.
+  #
+  # == When to use which
+  #
+  #   Page::Base    — one register, most scripts ("go through all pages in Reg X")
+  #   OrgPage::Base — entire org (cross-register audits, archive sweeps, bulk ops)
+  #
+  # == Subclass interface
+  #
+  #   class Custom::UseCase::ArchiveStaleDrafts < Eco::API::UseCases::GraphQL::Samples::Pages::OrgPage::Base
+  #     name 'archive-stale-drafts'
+  #     batch_size 100
+  #
+  #     def search_conf
+  #       super.filter(state_is(:draft))
+  #            .filter(updated_since('2025-01-01'))
+  #     end
+  #
+  #     def process_page(page)
+  #       return skip('already archived') if page.archived?
+  #       log(:info) { "Archiving: #{page.name}" }
+  #       graphql.page.archive(input: { id: page.id }) unless simulate?
+  #     end
+  #   end
+  class OrgPage::Base < Page::Base
+    name 'graphql-org-page-base'
+    type :other
+
+    require_relative 'dsl'
+    include Eco::API::UseCases::GraphQL::Samples::Pages::OrgPage::DSL
+
+    # No default register scope. Subclass adds filters via super.
+    def search_conf
+      sc.new
+    end
+  end
+end

data/lib/eco/api/usecases/graphql/samples/pages/org_page/dsl.rb

@@ -0,0 +1,8 @@
+module Eco::API::UseCases::GraphQL::Samples::Pages::OrgPage
+  # DSL concern for org-wide page use cases.
+  # Includes Page::DSL — all SearchConf helpers are available.
+  # Add org-page-specific helpers here as the pattern grows.
+  module DSL
+    include Eco::API::UseCases::GraphQL::Samples::Pages::Page::DSL
+  end
+end

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

@@ -0,0 +1,7 @@
+module Eco::API::UseCases::GraphQL::Samples::Pages
+  module OrgPage
+  end
+end
+
+require_relative 'org_page/dsl'
+require_relative 'org_page/base'

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

@@ -0,0 +1,148 @@
+module Eco::API::UseCases::GraphQL::Samples::Pages
+  # Base class for **register-scoped** page processing use cases.
+  #
+  # Provides the iteration + KPI scaffolding mirroring RegisterUpdateCase
+  # from OozeSamples, but working natively with the GraphQL stack.
+  #
+  # == Subclass interface
+  #
+  #   class Custom::UseCase::UpdateRiskRating < Eco::API::UseCases::GraphQL::Samples::Pages::Page::Base
+  #     name 'update-risk-rating'
+  #     register_id 'REG_ABC123'
+  #     batch_size 50
+  #
+  #     # Add filters on top of the default register scope.
+  #     def search_conf
+  #       super.filter(state_is(:active))
+  #            .filter(updated_since(options.dig(:filters, :from).to_s))
+  #     end
+  #
+  #     # Transform or act on each page; call update_page(page) to persist.
+  #     def process_page(page)
+  #       field = page.components.get_by_name('Risk Level')
+  #       return skip('no risk field') unless field
+  #       page.name = "[HIGH] #{page.name}" if field.value == 'High'
+  #       update_page(page)
+  #     end
+  #   end
+  #
+  # == What the base provides
+  # * process_page(page) — override point (required)
+  # * search_conf        — override point (optional; default scopes to register_id)
+  # * update_page(page)  — from_model + simulate? guard + error tracking
+  # * skip(reason)       — record a non-error skip
+  # * each_page          — cursor-paginated org search
+  # * KPI tracking       — total / processed / updated / skipped / failed
+  class Page::Base < Eco::API::UseCases::GraphQL::Base
+    name 'graphql-page-base'
+    type :other
+
+    require_relative 'dsl'
+    include Eco::API::UseCases::GraphQL::Samples::Pages::Page::DSL
+
+    class << self
+      def batch_size(size = nil)
+        @batch_size ||= 50
+        return @batch_size unless size
+        @batch_size = size
+      end
+
+      def register_id(id = nil)
+        @register_id = id if id
+        @register_id
+      end
+    end
+
+    attr_reader :total_pages, :processed_pages, :updated_pages
+    attr_reader :failed_pages, :skipped_pages
+
+    # Entry point — called by GraphQL::Base#main.
+    def process
+      init_kpis
+      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.
+    def process_page(_page)
+      raise NotImplementedError, "Implement #process_page in #{self.class}"
+    end
+
+    # Return a SearchConf for the page search. Override to add filters.
+    # Default: scoped to register_id when set, otherwise all pages.
+    def search_conf
+      conf = sc.new
+      reg  = self.class.register_id
+      conf = conf.filter(in_register(reg)) if reg
+      conf
+    end
+
+    protected
+
+    # Record a skip (not an error — the page was intentionally not processed).
+    def skip(reason = nil)
+      @skipped_pages += 1
+      log(:debug) { "Skipped#{reason ? ": #{reason}" : ''}" }
+    end
+
+    # Persist a page. Wraps Input::Page::Update.from_model, respects simulate?,
+    # and tracks KPIs. Returns nil on simulate or no-change; Response otherwise.
+    def update_page(page, **kargs)
+      if simulate?
+        @skipped_pages += 1
+        log(:debug) { "Simulate — would update page #{page.id}" }
+        return nil
+      end
+      response = graphql.pages.update(page, **kargs)
+      if response.nil?
+        @skipped_pages += 1
+      elsif response.success?
+        @updated_pages += 1
+      else
+        @failed_pages += 1
+        log(:error) { "Failed to update page #{page.id}: #{response.body}" }
+      end
+      response
+    end
+
+    # Cursor-paginated iteration over pages matching search_conf.
+    # Uses org search (currentOrganization.pages) — returns full PageUnion
+    # with patchVer and field IDs (required for update workflows).
+    def each_page(conf: search_conf, first: self.class.batch_size, &block)
+      graphql.pages.each(search_conf: conf.to_h, first: first) do |page|
+        @total_pages += 1
+        yield page
+      end
+    end
+
+    private
+
+    def init_kpis
+      @total_pages     = 0
+      @processed_pages = 0
+      @updated_pages   = 0
+      @failed_pages    = 0
+      @skipped_pages   = 0
+    end
+
+    def log_kpis
+      log(:info) { kpis_message }
+    end
+
+    def kpis_message
+      [
+        'Run end:',
+        "  * Pages found:     #{total_pages}",
+        "  * Pages processed: #{processed_pages}",
+        "  * Updated:         #{updated_pages}",
+        "  * Skipped:         #{skipped_pages}",
+        "  * Failed:          #{failed_pages}"
+      ].join("\n")
+    end
+  end
+end

data/lib/eco/api/usecases/graphql/samples/pages/page/dsl.rb

@@ -0,0 +1,38 @@
+module Eco::API::UseCases::GraphQL::Samples::Pages::Page
+  # DSL concern — included in Page::Base and available to all Page subclasses.
+  # Provides the SearchConf accessor and common filter shorthand methods.
+  #
+  # Include this in any class that needs SearchConf DSL access without
+  # inheriting the full Page::Base iteration scaffolding.
+  module DSL
+    private
+
+    # Lazy accessor for the SearchConf builder class.
+    # Resolved at runtime so the ecoportal-api-graphql gem is guaranteed to be loaded.
+    # Subclasses can also define a local constant for brevity:
+    #   SearchConf = Ecoportal::API::GraphQL::Input::SearchConf
+    def sc
+      Ecoportal::API::GraphQL::Input::SearchConf
+    end
+
+    # Convenience: build a register-scoped filter object.
+    def in_register(*ids)
+      sc.in_register(*ids)
+    end
+
+    # Convenience: build a state equality filter.
+    def state_is(value)
+      sc[:state].is(value)
+    end
+
+    # Convenience: build an externalId equality filter.
+    def external_id_eq(value)
+      sc[:external_id].eq(value)
+    end
+
+    # Convenience: build an updated_at since filter.
+    def updated_since(iso8601, time_zone: 'UTC')
+      sc[:updated_at].since(iso8601, time_zone: time_zone)
+    end
+  end
+end

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

@@ -0,0 +1,7 @@
+module Eco::API::UseCases::GraphQL::Samples::Pages
+  module Page
+  end
+end
+
+require_relative 'page/dsl'
+require_relative 'page/base'

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

@@ -0,0 +1,7 @@
+module Eco::API::UseCases::GraphQL::Samples
+  module Pages
+  end
+end
+
+require_relative 'pages/page'
+require_relative 'pages/org_page'

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

@@ -5,3 +5,4 @@ end
 
 require_relative 'samples/location'
 require_relative 'samples/contractors'
+require_relative 'samples/pages'

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

@@ -10,4 +10,5 @@ end
 require_relative 'graphql/helpers'
 require_relative 'graphql/utils'
 require_relative 'graphql/base'
+require_relative 'graphql/compat'
 require_relative 'graphql/samples'

data/lib/eco/api/usecases/ooze_samples/ooze_base_case.rb

@@ -224,6 +224,10 @@ class Eco::API::UseCases::OozeSamples::OozeBaseCase < Eco::API::Common::Loaders:
     return if options.dig(:feedback, :only_stats)
     return unless (patch = (patch_doc(entry) || {})['page'])
 
+    # Affirmative dry-run line so an empty/blank page no longer reads as a silent no-op.
+    # A create body carries :templateId (CreateFromTemplateInput); anything else is an update.
+    verb = patch.is_a?(Hash) && patch[:templateId] ? 'create' : 'update'
+    log(:info) { "[dry-run] would #{verb} #{object_reference(entry)} with:" }
     pp patch
   end
 

data/lib/eco/api/usecases/ooze_samples/register_update_case.rb

@@ -105,7 +105,13 @@ class Eco::API::UseCases::OozeSamples::RegisterUpdateCase < Eco::API::UseCases::
   def enqueue(object)
     return unless object.respond_to?(:id)
 
-    unless object.is_a?(Ecoportal::API::V2::Page) or object.is_a?(Ecoportal::API::V2::Pages::PageStage)
+    # Accept v2 Page/PageStage, or any duck-typed entry that carries change-tracking
+    # (the GraphQL compat page responds to #dirty? and #as_update). The strict v2-class
+    # guard otherwise raised for GraphQL pages under OozeRedirect.
+    queueable = object.is_a?(Ecoportal::API::V2::Page) ||
+                object.is_a?(Ecoportal::API::V2::Pages::PageStage) ||
+                (object.respond_to?(:dirty?) && object.respond_to?(:as_update))
+    unless queueable
       msg = "Queuing is just for entries. Expecting Page or PageStage. Given: #{object.class}"
       raise ArgumentError, msg
     end

data/lib/eco/version.rb

@@ -1,3 +1,3 @@
 module Eco
-  VERSION = '3.2.14'.freeze
+  VERSION = '3.2.16'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: eco-helpers
 version: !ruby/object:Gem::Version
-  version: 3.2.14
+  version: 3.2.16
 platform: ruby
 authors:
 - Oscar Segura
@@ -262,7 +262,7 @@ dependencies:
         version: '1.3'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.3.4
+        version: 1.3.9
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -272,7 +272,7 @@ dependencies:
         version: '1.3'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.3.4
+        version: 1.3.9
 - !ruby/object:Gem::Dependency
   name: ecoportal-api-v2
   requirement: !ruby/object:Gem::Requirement
@@ -541,6 +541,15 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".ai-assistance/conventions/code-working-tree-protocol.md"
+- ".ai-assistance/scripts/token-logger.js"
+- ".ai-assistance/scripts/token-report.ts"
+- ".ai-assistance/scripts/token-session-start.js"
+- ".ai-assistance/skills/ep-ai-manager/SKILL.md"
+- ".ai-assistance/skills/ruby-scripting/SKILL.md"
+- ".ai-assistance/standards-version.json"
+- ".ai-assistance/token-budget.json"
+- ".claude/settings.json"
 - ".gitignore"
 - ".idea/.gitignore"
 - ".markdownlint.json"
@@ -549,6 +558,7 @@ files:
 - ".ruby-version"
 - ".yardopts"
 - CHANGELOG.md
+- CLAUDE.md
 - Gemfile
 - LICENSE
 - README.md
@@ -740,6 +750,7 @@ files:
 - lib/eco/api/session/config/tagtree.rb
 - lib/eco/api/session/config/workflow.rb
 - lib/eco/api/usecases.rb
+- lib/eco/api/usecases/CLAUDE.md
 - lib/eco/api/usecases/base_case.rb
 - lib/eco/api/usecases/base_case/model.rb
 - lib/eco/api/usecases/base_case/type.rb
@@ -764,6 +775,7 @@ files:
 - lib/eco/api/usecases/default/meta.rb
 - lib/eco/api/usecases/default/meta/cli/graphql_schema_cli.rb
 - lib/eco/api/usecases/default/meta/graphql_schema.rb
+- lib/eco/api/usecases/default/pages.rb
 - lib/eco/api/usecases/default/people.rb
 - lib/eco/api/usecases/default/people/amend.rb
 - lib/eco/api/usecases/default/people/amend/clean_unknown_tags_case.rb
@@ -825,8 +837,15 @@ files:
 - lib/eco/api/usecases/default_cases/update_case.rb
 - lib/eco/api/usecases/default_cases/upsert_case.rb
 - lib/eco/api/usecases/graphql.rb
+- lib/eco/api/usecases/graphql/CLAUDE.md
 - lib/eco/api/usecases/graphql/base.rb
+- lib/eco/api/usecases/graphql/compat.rb
+- lib/eco/api/usecases/graphql/compat/ooze_redirect.rb
+- lib/eco/api/usecases/graphql/compat/ooze_redirect/dirty_array.rb
+- lib/eco/api/usecases/graphql/compat/ooze_redirect/field_patches.rb
+- lib/eco/api/usecases/graphql/compat/ooze_redirect/force_compat.rb
 - lib/eco/api/usecases/graphql/helpers.rb
+- lib/eco/api/usecases/graphql/helpers/CLAUDE.md
 - lib/eco/api/usecases/graphql/helpers/base.rb
 - lib/eco/api/usecases/graphql/helpers/base/case_env.rb
 - lib/eco/api/usecases/graphql/helpers/base/error_handling.rb
@@ -859,6 +878,7 @@ files:
 - lib/eco/api/usecases/graphql/helpers/location/tags_remap/tags_map.rb
 - lib/eco/api/usecases/graphql/helpers/location/tags_remap/tags_set.rb
 - lib/eco/api/usecases/graphql/samples.rb
+- lib/eco/api/usecases/graphql/samples/CLAUDE.md
 - lib/eco/api/usecases/graphql/samples/contractors.rb
 - lib/eco/api/usecases/graphql/samples/contractors/dsl.rb
 - lib/eco/api/usecases/graphql/samples/location.rb
@@ -885,6 +905,14 @@ files:
 - lib/eco/api/usecases/graphql/samples/location/service/tree_to_list/converter/node_attr_maps.rb
 - lib/eco/api/usecases/graphql/samples/location/service/tree_to_list/converter/parser.rb
 - lib/eco/api/usecases/graphql/samples/location/service/tree_to_list/output.rb
+- lib/eco/api/usecases/graphql/samples/pages.rb
+- lib/eco/api/usecases/graphql/samples/pages/CLAUDE.md
+- lib/eco/api/usecases/graphql/samples/pages/org_page.rb
+- lib/eco/api/usecases/graphql/samples/pages/org_page/base.rb
+- lib/eco/api/usecases/graphql/samples/pages/org_page/dsl.rb
+- lib/eco/api/usecases/graphql/samples/pages/page.rb
+- lib/eco/api/usecases/graphql/samples/pages/page/base.rb
+- lib/eco/api/usecases/graphql/samples/pages/page/dsl.rb
 - lib/eco/api/usecases/graphql/utils.rb
 - lib/eco/api/usecases/graphql/utils/sftp.rb
 - lib/eco/api/usecases/lib.rb