eco-helpers 3.3.1 → 3.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 573a9ed21173c949849363f9e92875fc79981e410144a6c3fe101fdfcd4b9062
-  data.tar.gz: c12a639bb7775e0d43459c5bfe534fae12552c760d608b2192c052b12c1828a0
+  metadata.gz: 3c5e64bb2f9a25359774eb01482180a7efdbade0e2b6e4d02a56a4c9dbb1d91f
+  data.tar.gz: ea2fd73dc9709ca1710e9aff527f0ae856a55fe0638a7c3862b71bfd9ce5270c
 SHA512:
-  metadata.gz: a3fb82eb08b5421db3bcca403257eb694aaf4844ed11c82c2e2a66211b9a13d14ae4b7941c42a720b74e5b5e09df39f8846223ed777cf21095d42d0086a73f89
-  data.tar.gz: c51eb9e14c75aedb26e68562d15801de0bbaf376983254d809ed0024968c1a4117de12e2f6444647ad75ce51f50847d684d5261d3b10e6897bd8454f6e7ef9af
+  metadata.gz: 37dfa8178019e8a4854f3b98386682def2ff8f51b1f7c9dcf95dff4947eea662f14145ab93434ceb8f749acc7981d6904114bc8ad8f4f6d251ed217a28a43ce5
+  data.tar.gz: 4653193b58ac2f88bb76b06c4ee094331b2f034ccae4929d5722398105e2035a982e136fd6fda78d207c33e5ddc4aff9f5c489a11abd155382607d94bca8105d

data/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 All notable changes to this project will be documented in this file.
 
+## [Unreleased]
+
+## [3.3.3] - 2026-09-30
+
+Security republish of 3.3.2. **Backwards-compatible; no code change**: same dependencies, same
+behaviour. Supersedes the published versions of this line, which are to be yanked.
+
+### Security
+
+- Removed customer and internal identifiers from shipped code comments and this changelog (a
+  comment listing customer organisations and their case names; internal repository names and
+  internal documentation paths). Comments and changelog only.
+- Packaging: the three runtime JSON files are declared in `.release-smoke-allow`, and the release
+  tasks accept `release/*` maintenance branches.
+
+## [3.3.2] - 2026-09-02
+
+### Fixed
+
+- Gemspec `spec.files` allowlisted by ROOT DIRECTORY (`lib/`, `exe/`) rather than by full path,
+  so any non-`.rb` file added under `lib/` shipped silently. As of 3.3.1 that was five `CLAUDE.md`
+  agent-instruction files under `lib/eco/api/usecases/`. `spec.files` is now a full-path
+  allowlist — `lib/**/*.rb`, three named JSON files genuinely read at runtime
+  (`preferences_reference.json`, `presets_integrity.json`, `presets_values.json`), and
+  `README.md` / `CHANGELOG.md` / `LICENSE` at the root — intersected with `git ls-files`.
+  `spec/packaging_spec.rb` pins the allowlist so this cannot regress silently again.
+
 ## [3.3.1] - 2026-08-13
 
 ### Fixed
@@ -11,7 +38,7 @@ All notable changes to this project will be documented in this file.
   actual bytes. Both read branches (BOM and plain) now use binary mode (`mode: 'rb'`), preserving
   the bytes exactly; BOM stripping is unchanged. Linux behaviour is identical before and after
   (text mode never translated anything there) — this makes Windows match Linux. Surfaced by Travis
-  on the mns EPT-1607 tooltip CSV (multi-org-idle `BLOCKED-TR-04`).
+  on a customer's tooltip CSV (reported from a downstream script repo).
 
   **Precision note (2026-08-13, verified against the motivating file before this version was
   tagged):** the earlier draft of this entry claimed `Eco::CSV.read` raised
@@ -51,7 +78,7 @@ depends on whether the consumer also declares graphql directly:
 - A consumer declaring **only** `eco-helpers '~> 3.2'` adopts 3.3.0 on its next `bundle update`,
   and reaches **graphql 2.0.0 transitively**.
 - A consumer declaring **both** `eco-helpers '~> 3.2'` and `ecoportal-api-graphql '~> 1.3'` (which
-  is the case for `multi_org_api` and `multi-org-idle`) does **not** silently adopt — it **fails to
+  is the case for two internal script repos) does **not** silently adopt — it **fails to
   resolve**, because 3.3.0 requires graphql `~> 2.0`.
 
 So the "2.0.0 gates adoption for free" argument only ever covered **direct** graphql dependencies.
@@ -60,7 +87,7 @@ Both consumers were pinned deliberately on 2026-08-13 rather than left to discov
 ★ **`3.2.20` was tagged but deliberately NEVER PUBLISHED.** rubygems goes 3.2.19 → 3.3.0. The tag
 marks real history (the point where the 3.2.19 hotfix line rejoined master) but the gem was not
 pushed, and **must not be**: it predates the `spec.files` allowlist fix below and would ship
-internal `.ai-assistance/` and `docs/` content to rubygems. Its content is not lost — 3.3.0
+internal AI-tooling and `docs/` content to rubygems. Its content is not lost — 3.3.0
 descends from it. Anything needing the `Eco::API::Custom::Cli` reunification must use **3.3.0**,
 not a `~> 3.2.0` pin.
 
@@ -75,7 +102,7 @@ check.
 recorded, treat any `OozeRedirect` run against customer data as unproven — dry-run first.
 
 ★ **The published gem is now `lib/` only.** `spec.files` excluded just `test|spec|features`, so
-every top-level directory added since shipped by default — `.ai-assistance/` internal notes,
+every top-level directory added since shipped by default — internal AI-tooling notes,
 `docs/` (including the rolling worklog) and `.claude/`. `spec.files` is now an allowlist
 (`lib/`, `exe/`, README, LICENSE, CHANGELOG). All `lib/` files are unchanged; nothing outside
 `lib/` was ever loaded at runtime. Same fix as `ecoportal-api-graphql` 2.0.0.
@@ -84,7 +111,7 @@ every top-level directory added since shipped by default — `.ai-assistance/` i
 
 Reunites the released `3.2.19` hotfix line with `master`. `3.2.19` was cut from the `v3.2.18` tag
 and **never merged back**, so two halves were split across branches: `master` carried
-`Eco::API::Custom::Cli` (unreleased since 2026-07-25, and the reason `mns/config/cli.rb` could not
+`Eco::API::Custom::Cli` (unreleased since 2026-07-25, and the reason a downstream CLI could not
 load on any published gem) while `3.2.19` carried the ooze KPI counter fix and the graphql floor.
 This release carries both. Dependency floors are the max of each side.
 
@@ -145,7 +172,7 @@ replaces on release.
 
 ## [3.2.19] - 2026-07-16
 
-Farmers / `cans-upsert` reliability adoption + an ooze KPI counter fix. **Backwards-compatible.**
+A customer's `cans-upsert` reliability adoption + an ooze KPI counter fix. **Backwards-compatible.**
 Cut from the `v3.2.18` tag (not `master`, which carries the native GraphQL activity/dashboard
 readers depending on the unreleased gem `1.4.0`), so this ships needing only the published
 `ecoportal-api-graphql 1.3.14`.
@@ -178,7 +205,7 @@ guard so the dead-fragment class of bug can't reach production again.
 on 2026-07-04 (`243822b9`), then the live-crash fix `352a9657` (LocationDraft dead-fragment
 convention) landed on 2026-07-05 — keeping the same `3.2.17` label. Because `3.2.17` is installed
 from git/path (unpublished), a consumer bundled in that ~26h window reports `3.2.17` yet lacks the
-fix. This crashed the **live act-gov** org-structure sync again on 2026-07-09 with the exact
+fix. This crashed the **live customer** org-structure sync again on 2026-07-09 with the exact
 `uninitialized constant …Fragment::LocationDraft (NameError)`. Bumping to `3.2.18` makes the fixed
 build unambiguously identifiable: any consumer on `>= 3.2.18` provably has the fix.
 
@@ -187,7 +214,7 @@ build unambiguously identifiable: any consumer on `>= 3.2.18` provably has the f
 - **Regression-guard spec for the dead-fragment convention.**
   `spec/…/helpers/location/command/end_points/optimizations_spec.rb` scans every file under
   `usecases/graphql/` and fails if any references a fragment via the removed `___Const__Fragment` /
-  `::Fragment::<Name>` constant convention (the exact NameError that crashed act-gov), and asserts
+  `::Fragment::<Name>` constant convention (the exact NameError that crashed a customer sync), and asserts
   the three Location command payload procs still route fragments through the `spread :Name` registry
   DSL. It is a SOURCE lint, not a full offline render: rendering needs the graphlient fork's
   `to_query_string`/`spread` DSL, but eco-helpers' own bundle resolves stock graphlient `0.8.0` (the
@@ -212,7 +239,7 @@ to the gem's `Diff` module (gem v1.3.11), which is tagged but unpublished.
   `___Const__Fragment` constant convention (`___Ecoportal__API__GraphQL__Fragment__LocationDraft` /
   `…__LocationsError`), which the gem's registry-based fragments no longer expose as Ruby constants →
   `uninitialized constant … Fragment::LocationDraft (NameError)` when building a locations-draft
-  `addCommands`/`create`/`publish` request. Crashed the live act-gov tagtree / org-structure sync.
+  `addCommands`/`create`/`publish` request. Crashed a customer's live tagtree / org-structure sync.
   Now `spread :LocationDraft` / `spread :LocationsError`, matching the gem.
 
 ### Dependencies
@@ -220,7 +247,7 @@ to the gem's `Diff` module (gem v1.3.11), which is tagged but unpublished.
 - **Raised floors to the fixed stack: `ecoportal-api-graphql >= 1.3.11`, `ecoportal-api-v2 >= 3.3.3`.**
   Stops the stale gem 1.3.9 (missing the LocationStructure `updatedAt`/`createdAt` selection fixes from
   1.3.10) and the buggy v2 3.3.2 (Ruby-3.x `DoubleModel` cascade `TypeError`) from resolving on
-  consumers — both crashed the live act-gov integration.
+  consumers — both crashed a customer's live integration.
 
 ### Added
 

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

@@ -62,19 +62,8 @@ module Eco::API::UseCases::GraphQL::Compat
   #   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
+  # Affected cases currently blocked: roughly half of all ooze cases in the internal script repos'
+  # survey (per-customer breakdown kept in the internal migration notes, not in this gem).
   #
   # Implementation sketch (to be built when the endpoint lands):
   #

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

@@ -7,7 +7,7 @@ module Eco::API::UseCases::GraphQL::Helpers
   # with duck-typing so they work against the GraphQL page/section/field models.
   #
   # This is Phase 1 of the ooze -> native GraphQL migration (build the shared substrate before
-  # any case). See ecoportal-api-graphql/.ai-assistance/projects/ooze-graphql-native-migration/.
+  # any case). See the ecoportal-api-graphql repo's internal docs.
   module Pages
   end
 end

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

@@ -115,8 +115,15 @@ module Eco::API::UseCases::GraphQL::Samples::Pages
         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)
+        #
+        # `value:` is a REQUIRED keyword -- the backend's AddSelectFieldOptionInput declares
+        # `argument :value, String, required: true`, and it is the option's unique key (cast to a
+        # number for numeric select fields). There is no default and it is never derived here from
+        # label/weight/position: a plausible-looking derived value would silently store WRONG data on
+        # exactly the scored fields this feature is used for. Callers must supply an explicit value.
+        def option(label:, value:, weight: nil)
+          @emitter.emit(:addSelectFieldOption, data_field_id: @field_id, label: label, value: value,
+                                               weight: weight)
           @field_id
         end
       end

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

@@ -111,7 +111,7 @@ module Eco::API::UseCases::GraphQL::Samples::Pages::Template
           description: field.description
         ) do |field_builder|
           Array(field.options).each do |opt|
-            field_builder.option(label: opt[:label], weight: opt[:weight])
+            field_builder.option(label: opt[:label], value: opt[:value], weight: opt[:weight])
           end
         end
       end

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

@@ -15,8 +15,17 @@ module Eco::API::UseCases::GraphQL::Samples::Pages::Template
     #
     #   * `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_options`  — for select-type fields: pipe-separated `label:value:weight`
+    #                        triples, e.g. "High:10:10|Medium:5:5|Low:0:0". `value` is the
+    #                        backend's unique, REQUIRED select-option key (cast to a number for
+    #                        numeric select fields) -- NEVER derived from label/weight/position
+    #                        here, because a derived value can collide (duplicates are rejected
+    #                        server-side) or silently store the WRONG number on a scored field.
+    #                        Weight optional via a trailing empty part, e.g. "High:H:|Low:L:". A
+    #                        cell resolving to exactly two parts (the OLD `label:weight`
+    #                        shorthand -- now ambiguous with a value-only `label:value`) or a
+    #                        bare label RAISES ArgumentError naming the field, option label, and
+    #                        offending cell -- see `#options` below.
     #   * `field_description` — carries the SECTION/FIELD IDENTITY convention (see below).
     #
     # SECTION / FIELD IDENTITY CONVENTION (per the CSV-pipeline project notes): stable identity for a
@@ -68,20 +77,50 @@ module Eco::API::UseCases::GraphQL::Samples::Pages::Template
           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))
+          field_options:     options(value(row, :field_options), field_label: value(row, :field_label))
         )
       end
 
-      # Parse the options cell into [ { label:, weight: }, ... ]. Empty → [].
-      def options(cell)
+      # Parse the options cell into [ { label:, value:, weight: }, ... ]. Empty → [].
+      #
+      # `field_label:` is ONLY used for the ArgumentError message below -- it identifies which field's
+      # options cell is malformed, since a builder raising mid-batch on a 500-row CSV is otherwise
+      # nearly impossible to trace back to the offending row.
+      def options(cell, field_label: nil)
         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) }
+          option_from_token(token, field_label: field_label, cell: cell)
         end
       end
 
+      # A token must resolve to exactly `label:value` or `label:value:weight` (weight optional, via a
+      # present-but-empty third part). Anything else -- a bare label, or exactly two parts -- means no
+      # explicit `value` was given. Because a `label:X` two-part cell is indistinguishable from the OLD
+      # `label:weight` shorthand, it is REJECTED rather than guessed at: see the module doc for why a
+      # derived value is worse than a loud failure.
+      def option_from_token(token, field_label:, cell:)
+        parts = token.split(OPTION_WEIGHT_SEPARATOR, 3).map(&:strip)
+        label = parts[0].to_s.empty? ? nil : parts[0]
+        value = parts[1]
+
+        if parts.size < 3 || value.nil? || value.empty?
+          raise ArgumentError, missing_option_value_message(field_label, label || token, cell)
+        end
+
+        weight_raw = parts[2]
+        { label: label, value: value,
+          weight: (weight_raw && !weight_raw.empty? ? Integer(weight_raw, exception: false) : nil) }
+      end
+
+      def missing_option_value_message(field_label, option_label, cell)
+        "select option is missing an explicit `value` (field: #{field_label.inspect}, " \
+          "option: #{option_label.inspect}, cell: #{cell.to_s.inspect}). The old `label:weight` " \
+          'two-part shorthand is no longer accepted -- addSelectFieldOption requires a unique, ' \
+          'non-derived `value` per option. Add one explicitly, e.g. ' \
+          "\"#{option_label}:VALUE\" or \"#{option_label}:VALUE:WEIGHT\"."
+      end
+
       def value(row, logical)
         header = COLUMNS.fetch(logical)
         raw    = row[header]

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

@@ -1,6 +1,6 @@
 module Eco::API::UseCases::GraphQL::Samples::Pages
   # Template (workflow) build-from-scratch + (later) diff-and-update samples.
-  # See ecoportal-api-graphql/.ai-assistance/projects/template-maintenance/.
+  # See the ecoportal-api-graphql repo's internal docs.
   module Template
   end
 end

data/lib/eco/version.rb

@@ -1,3 +1,3 @@
 module Eco
-  VERSION = '3.3.1'.freeze
+  VERSION = '3.3.3'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: eco-helpers
 version: !ruby/object:Gem::Version
-  version: 3.3.1
+  version: 3.3.3
 platform: ruby
 authors:
 - Oscar Segura
@@ -731,7 +731,6 @@ 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
@@ -818,7 +817,6 @@ 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
@@ -829,7 +827,6 @@ files:
 - lib/eco/api/usecases/graphql/compat/parity/harness.rb
 - lib/eco/api/usecases/graphql/compat/parity/run_result.rb
 - lib/eco/api/usecases/graphql/helpers.rb
-- lib/eco/api/usecases/graphql/helpers/CLAUDE.md
 - lib/eco/api/usecases/graphql/helpers/access_logs.rb
 - lib/eco/api/usecases/graphql/helpers/access_logs/base.rb
 - lib/eco/api/usecases/graphql/helpers/access_logs/base/reader.rb
@@ -879,7 +876,6 @@ files:
 - lib/eco/api/usecases/graphql/helpers/pages/shortcuts.rb
 - lib/eco/api/usecases/graphql/helpers/pages/typed_fields_pairing.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
@@ -907,7 +903,6 @@ files:
 - 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

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

@@ -1,78 +0,0 @@
-# usecases
-
-The use-case registry and all built-in case base classes for scripting against EcoPortal.
-
----
-
-## What a use case is
-
-A use case is a self-contained, named, runnable unit of work. It registers itself with
-the CLI framework, receives `session`, `options`, and `usecase` from the runner, and
-executes its `process` (or `process_ooze` / `process_page`) method.
-
-```
-CLI invokes rake → rake finds registered case → UseCase#launch → main() → process()
-```
-
----
-
-## Directory structure
-
-| Path | What lives there |
-|------|-----------------|
-| `graphql/` | GraphQL-native base cases + samples (see `graphql/CLAUDE.md`) |
-| `ooze_samples/` | APIv2/REST base cases: `OozeBaseCase`, `RegisterUpdateCase` |
-| `ooze_cases/` | Concrete built-in ooze cases (export register, etc.) |
-| `default/` | Built-in people, location, and utility cases |
-| `default_cases/` | Loader and samples for default cases |
-| `samples/` | Misc driver samples |
-| `graphql.rb` | GraphQL use case loader |
-| `ooze_samples.rb` | Ooze/REST use case loader |
-| `default.rb` | Default use case loader |
-
----
-
-## Adding a new use case
-
-1. Subclass the appropriate base:
-
-   | Your use case | Inherit from |
-   |---|---|
-   | Process pages in a register (update workflow) | `Eco::API::UseCases::GraphQL::PageCase` |
-   | Process pages org-wide (cross-register, audit) | `Eco::API::UseCases::GraphQL::OrgPageCase` |
-   | Custom GraphQL script (export, report, one-off) | `Eco::API::UseCases::GraphQL::Base` |
-   | Legacy APIv2 register update | `Eco::API::UseCases::OozeSamples::RegisterUpdateCase` |
-
-2. Set `name` and `type`:
-   ```ruby
-   name 'my-case-name'   # CLI identifier: called with -my-case-name
-   type :other           # :people | :contractors | :other
-   ```
-
-3. Override the entry point (`process_page`, `process`, or `process_ooze`).
-
-4. Register in the org's `config/cli.rb`:
-   ```ruby
-   cases.add('-my-case-name', :other, 'Description')
-   ```
-
----
-
-## How cases are launched
-
-`Eco::API::UseCases::UseCase#launch` calls `callback.call(*uio.params)` where the
-callback is bound to `method(:main)`. Before launch, `@session` and `@options` are
-injected into the instance — subclasses access them via the `attr_reader` in `CaseEnv`.
-
-The `:other` type passes `(session, options, usecase)` positionally to `main`.
-For `GraphQL::Base` subclasses the signature is `main(*_args)` — `session` and
-`options` are already available via the helpers module before `main` is called.
-
----
-
-## Related
-
-- `graphql/CLAUDE.md` — GraphQL case hierarchy, PageCase/OrgPageCase
-- `ooze_samples/` — legacy v2 cases (RegisterUpdateCase, OozeBaseCase)
-- `eco-helpers/CLAUDE.md` — top-level gem context
-- `ecoportal-api-graphql` — upstream gem providing `SearchConf`, `Compat::Pages`, etc.

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

@@ -1,120 +0,0 @@
-# usecases/graphql
-
-GraphQL-native use case base classes and helpers. All cases here work directly with
-`ecoportal-api-graphql` — no v2 REST layer, no ooze objects.
-
----
-
-## Class hierarchy
-
-```
-Eco::API::Common::Loaders::UseCase                           (registration + launch)
-    ↓
-Eco::API::UseCases::GraphQL::Base                            ← universal GraphQL env
-    ├── GraphQL::Samples::Pages::Page::Base                  ← register-scoped pages
-    │       ├── GraphQL::Samples::Pages::OrgPage::Base       ← org-wide pages
-    │       └── your subclass (process_page, search_conf)
-    └── your subclass directly (custom scripts: exports, reports, one-offs)
-```
-
-Samples live under `samples/pages/` — NOT in the `graphql/` root. The root only
-has `base.rb`, `helpers.rb`, `utils.rb`, and `samples.rb`.
-
----
-
-## Base — `graphql/base.rb`
-
-Universal GraphQL environment. Provides `graphql`, `session`, `options`, `config`,
-`simulate?`, `log`, `backup` via `Helpers::Base` (see `helpers/CLAUDE.md`).
-
-Override `process` to write your script:
-```ruby
-class MyCase < Eco::API::UseCases::GraphQL::Base
-  name 'my-case'
-  def process
-    graphql.currentOrganization.contractorEntities.each { |c| puts c.name }
-  end
-end
-```
-
----
-
-## Pages — `samples/pages/`
-
-Page processing base cases. Follow the hierarchy: `page/base` → `org_page/base`.
-
-### `samples/pages/page/base.rb` — `Samples::Pages::Page::Base`
-
-For **register-scoped** page update workflows.
-
-**Class methods:** `register_id 'REG_ID'`, `batch_size 50` (default)
-
-**Override points:**
-- `process_page(page)` — **required** — transformation for one page
-- `search_conf` — optional — call `super` to keep register scope, then add filters
-
-**Protected helpers:** `update_page`, `skip(reason)`, `each_page`
-
-**KPI readers:** `total_pages`, `processed_pages`, `updated_pages`, `skipped_pages`, `failed_pages`
-
-**DSL (via `samples/pages/page/dsl.rb`):** `sc`, `in_register`, `state_is`, `external_id_eq`, `updated_since`
-
-```ruby
-class Custom::UseCase::UpdateStatus < Eco::API::UseCases::GraphQL::Samples::Pages::Page::Base
-  name 'update-status'
-  register_id 'REG_ABC'
-
-  def search_conf
-    super.filter(state_is(:active))
-  end
-
-  def process_page(page)
-    page.name = page.name.upcase
-    update_page(page)
-  end
-end
-```
-
-### `samples/pages/org_page/base.rb` — `Samples::Pages::OrgPage::Base`
-
-Inherits `Page::Base`. `search_conf` starts empty (org-wide, no register scope).
-Use for: archive sweeps, cross-register audits, bulk org operations.
-
----
-
-## Samples — `graphql/samples/`
-
-Built-in ready-to-use case implementations:
-- `samples/location.rb` — location structure management cases
-- `samples/contractors.rb` — contractor entity cases
-
-See `samples/CLAUDE.md` for details.
-
----
-
-## Helpers — `graphql/helpers/`
-
-Mixins providing domain-specific access patterns. See `helpers/CLAUDE.md`.
-
----
-
-## Loader order in `graphql.rb`
-
-```ruby
-require 'graphql/helpers'   # environment mixins (graphql, session, simulate? etc.)
-require 'graphql/utils'     # utility modules (SFTP etc.)
-require 'graphql/base'      # GraphQL::Base — universal foundation
-require 'graphql/samples'   # sample cases: location, contractors, pages, ...
-  # └─ graphql/samples/pages.rb
-  #      └─ pages/page.rb        → page/dsl.rb, page/base.rb
-  #      └─ pages/org_page.rb    → org_page/dsl.rb, org_page/base.rb
-```
-
-Page base cases are in `samples/pages/` — NOT in the `graphql/` root.
-Custom org cases are NOT loaded here — they live in the implementation repo.
-
-## default/pages/
-
-CLI-integrated page use cases go in `default/pages/` (mirroring `default/locations/`
-and `default/people/`). Currently empty — add cases there when a pattern is common
-enough to expose to all org environments. See `default/pages.rb` for the convention.

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

@@ -1,79 +0,0 @@
-# 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`).

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

@@ -1,76 +0,0 @@
-# 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

@@ -1,59 +0,0 @@
-# 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.