eco-helpers 3.2.22 → 3.2.23

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f79a58827dc2789ddfcc56e108d93520af92c15152b94338ca51e73cc388210
-  data.tar.gz: e15e69fdb8fa6bd37202aad7f01bebcda80c9aadacc23333a98846a27aeddffd
+  metadata.gz: 2803cb1dc211ef8682ebcd33e4007f4e748b5eb42f56ecbaa931b5258064ead8
+  data.tar.gz: 7c0f5f66654761ce6ee5cb37ca4eb354054161c0fc3914c37da27f7f6fce4273
 SHA512:
-  metadata.gz: 14faa786d74eb1b096cea772f79903df7f16e0dd903ce8586621f4524413795f0720bad631b0ddbc892cee01d12e6445f2af5ff6ff808d5754bb8593959f5d9a
-  data.tar.gz: b8b28cba91173036b005e3aa9a8e88e0143a932e1342c4aa91f085c73d4e031191e5f09c8f71928547392e41291c8b0128d0455b1b646ab93422247b9cac57b9
+  metadata.gz: 10235574cf1a38826f4de995d715747b65fd657e0ef4e183b04644f8e26bebb2471c4d118fbbc00eac72e174d74c72d4685c9fb49a9a3667d8320c005ef7983a
+  data.tar.gz: e9f15c9f0e9c5243c835402fe64efd1384021773d3e0c0d65fbbfe17bd10128e944932e9a8ac21501cf31025040c9fcc0b2b26b8eb70844fd631f899008c822c

data/CHANGELOG.md

@@ -2,13 +2,27 @@
 
 All notable changes to this project will be documented in this file.
 
+## [3.2.23] - 2026-09-30
+
+Security republish of 3.2.22. **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. It also carries the full-path packaging allowlist from 3.3.2, so the five internal
+  `CLAUDE.md` files that 3.2.22 packaged under `lib/` no longer ship.
+- Packaging: the three runtime JSON files are declared in `.release-smoke-allow`, and the release
+  tasks accept `release/*` maintenance branches.
+
 ## [3.2.22] - 2026-08-14
 
 ### Fixed
 
 - Republish of `3.2.21`: its `lib/eco/version.rb` shipped with doubled carriage returns
-  (`
-` line endings), causing a `warning: encountered 
 in middle of line` on every
+  (`
+` line endings), causing a `warning: encountered  in middle of line` on every
   load. Functionally identical otherwise; `3.2.21` will be yanked.
 
 ## [3.2.21] - 2026-08-14
@@ -16,7 +30,7 @@ All notable changes to this project will be documented in this file.
 ### Fixed
 
 - Packaging-only republish of `3.2.19` with an allowlisted gemspec (backported from `3.3.0`).
-  Versions `3.2.16`-`3.2.19` shipped internal repository content (`.ai-assistance/` tooling,
+  Versions `3.2.16`-`3.2.19` shipped internal repository content (the repo's internal docs tooling,
   `.claude/settings.json`) to rubygems.org via the old denylist `spec.files`; `3.2.19` is
   yanked and `3.2.16`/`3.2.18` are queued for deletion by RubyGems support. `3.2.21` is the
   identical `lib/` code packaged clean, so constraints like `'~> 3.2.0', '>= 3.2.19'` keep
@@ -26,7 +40,7 @@ All notable changes to this project will be documented in this file.
 
 ## [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`.
@@ -59,7 +73,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.
 
@@ -68,7 +82,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
@@ -93,7 +107,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
@@ -101,7 +115,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.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.2.22'.freeze
+  VERSION = '3.2.23'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: eco-helpers
 version: !ruby/object:Gem::Version
-  version: 3.2.22
+  version: 3.2.23
 platform: ruby
 authors:
 - Oscar Segura
@@ -730,7 +730,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
@@ -817,7 +816,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
@@ -828,7 +826,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/base.rb
 - lib/eco/api/usecases/graphql/helpers/base/case_env.rb
 - lib/eco/api/usecases/graphql/helpers/base/error_handling.rb
@@ -869,7 +866,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
@@ -897,7 +893,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.