eco-helpers 3.2.23 → 3.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2803cb1dc211ef8682ebcd33e4007f4e748b5eb42f56ecbaa931b5258064ead8
-  data.tar.gz: 7c0f5f66654761ce6ee5cb37ca4eb354054161c0fc3914c37da27f7f6fce4273
+  metadata.gz: 2c1f4723827d6dabfa094fd943b573a00bfe19c6d16b4ea0cb528c01d23d74d0
+  data.tar.gz: 6cb1e6109c1d4150f2a52c0359941b02be893065cc6b732932af117ad6bbd08c
 SHA512:
-  metadata.gz: 10235574cf1a38826f4de995d715747b65fd657e0ef4e183b04644f8e26bebb2471c4d118fbbc00eac72e174d74c72d4685c9fb49a9a3667d8320c005ef7983a
-  data.tar.gz: e9f15c9f0e9c5243c835402fe64efd1384021773d3e0c0d65fbbfe17bd10128e944932e9a8ac21501cf31025040c9fcc0b2b26b8eb70844fd631f899008c822c
+  metadata.gz: 515a129e3e75c42d0c16de5154a0e06e7d5854b65e766cf7e144b7097b6e55f2d2db5130ee05828f3c672da57f443517198816df18523ff952aefd8d93f9a645
+  data.tar.gz: aa5c685e34346dfe3bc41c006c89790eba83470327d950eeb531b0416b14228616d8cee57ba6d9f82d351db5ef3d4d6aa6a45aa147c6702821a1454a730fe879

data/CHANGELOG.md

@@ -2,45 +2,98 @@
 
 All notable changes to this project will be documented in this file.
 
-## [3.2.23] - 2026-09-30
+## [3.3.0] - 2026-08-13
+
+Adopts **`ecoportal-api-graphql` 2.0.0** (published 2026-08-13): floor raised from
+`~> 1.3, >= 1.3.14` to `~> 2.0, >= 2.0.0`. Minor rather than major here — 2.0.0's breaking set
+removed surfaces that either targeted mutations the live schema never had or were dead accessors,
+and a sweep of this repo finds **no consumer of any of them** (`editPage`,
+`editPageCreatorPermissions`, the AI-summary mutations, the SmartFill pair — zero hits outside
+this repo's own readiness notes). Nothing in `lib/` changes behaviour as a result of the bump.
+
+★ **What starts WORKING, which matters more here than what broke.** Several paths were sending
+documents the schema rejected, so they always errored; on 2.0.0 they really write. For this gem
+the one to watch is the **`OozeRedirect` force path** — malformed `executeWorkflowCommands` until
+graphql 1.3.15 fixed it, so its behaviour flips from "always errored" to "really writes" with no
+signature change to warn anyone. **Re-verify it on a sandbox org before trusting it in a customer
+run.** Also newly live via the gem: the page-level `executeWorkflowCommands` bus, File-field
+attach writes, `updatePresetView` column edits, viewable-field management and Date-field renewals.
+
+Consumers pinned to `~> 3.2` do not pick this up automatically, so adopting graphql 2.0.0 stays a
+deliberate per-repo decision.
+
+★ **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,
+`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.
+
+## [3.2.20] - 2026-08-11
+
+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
+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.
+
+### Native GraphQL activity/dashboard readers + contractor manager-settings write
+
+Additive, all **NATIVE** (no `Compat::` layer). Depends on the `ecoportal-api-graphql`
+`feat/graphql-activity-logs` branch (polymorphic `activityLogs` / `page.activities` models);
+during development it is wired via a temporary Gemfile `path:` override that a gem version bump
+replaces on release.
+
+### Changed
+
+- `ecoportal-api` dependency floor raised to `0.10.17`: inherits the `WithRetry` fix making
+  `HTTP::TimeoutError` retryable (transient timeouts no longer kill batch loops).
+
+### Added
+
+- **Shared connection-reader substrate** — `Helpers::Base::ConnectionReader`: an `Enumerable`
+  mixin that wraps the gem's lazy `QueryConnection#each` (cursor pagination over
+  `pageInfo.endCursor`/`hasNextPage`) behind a uniform `each` / `to_a(limit:)` / `page_size`
+  surface. All new readers build on it.
+- **System Access Logs reader** — `Helpers::AccessLogs::Base#access_logs` over
+  `currentOrganization.activityLogs`, exposing the full filter set (user_ids, resource_ids,
+  filter_superusers, activity_type, resource_type, source, date_filter) → yields `Model::ActivityLog`.
+- **Page history reader** — `Helpers::Pages::Activities#page_activities` over `page(id:).activities`
+  (page id + `sorters:`/`search_conf:` + lazy pagination) → yields `Model::Activity`.
+- **Dashboards reader** — `Helpers::Dashboards::Base#dashboards` over `dashboardSearch` → yields
+  `Model::MinimalDashboard`.
+- **Contractor manager-settings WRITE** — `Helpers::Contractors::Base::ManagerSettings#update_contractor_manager_settings`
+  (also exposed via `Samples::Contractors::DSL#update_manager_settings`), driving the gem's
+  `Builder::ContractorEntity#update_manager_settings`. Guarded: **dry-run/simulate** short-circuits
+  before any mutation (returns the intended input); **-no-email** discipline honoured
+  (`options.workflow.no_email` or explicit `no_email:` suppresses the helper's own notification).
+- **Thin live drivers** under `tests/` (read-only for the three readers; dry-run-only for the
+  contractor write) plus a shared `tests/env_graphql.rb` harness.
+- Offline specs for all of the above (23 examples).
+- `Eco::API::Common::Loaders::CliConfig` exposed via `Eco::API::Custom::Cli`.
+
+### Fixed
+
+- **`Template::Base` could never run — `CommandEmitter` was unresolvable.** The class was declared
+  with the compact `class Template::Base` form inside `module ...::Pages`, which leaves `Template`
+  out of the file's lexical scope, so the bare `CommandEmitter` reference in `#desired_commands`
+  raised `NameError` on every call — meaning every build-from-scratch template use case failed
+  before emitting a single command. Now nested as `module Template` + `class Base`, matching the
+  sibling files (`command_emitter.rb`, `csv_build/builder.rb`) whose bare cross-references already
+  worked for exactly that reason. Public constant path is unchanged. Found by the first spec ever
+  written against this class.
 
-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
-  load. Functionally identical otherwise; `3.2.21` will be yanked.
-
-## [3.2.21] - 2026-08-14
-
-### 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 (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
-  resolving on the 3.2 line (its graphql dependency stays `~> 1.3`, satisfied by the clean
-  `1.3.16`). The version number `3.2.20` is intentionally skipped: it exists as a
-  tagged-but-deliberately-unpublished version (see the 3.3.0-era changelog corrections).
+- **Ooze update KPI counters now count GraphQL updates.** `RegisterUpdateCase` tallied
+  `updated`/`failed` only when the result `is_a?(Ecoportal::API::Common::Response)`, but the
+  GraphQL compat layer returns an `Ecoportal::API::GraphQL::Compat::Response` (duck-types
+  `success?`/`status`, not in that class hierarchy) — so GraphQL updates were silently
+  uncounted (`Updated 0 (attempted: N)`, `Failed 0`) even when the write applied. Guard is now
+  `respond_to?(:success?)`; `false`/`nil` (dry-run / no-op) still skip. Inherited by
+  `TargetOozesUpdateCase` → TOOCS / cans-upsert. Also shipped as the maintenance release
+  `3.2.19` off `v3.2.18`; regression spec added.
 
 ## [3.2.19] - 2026-07-16
 
-A customer's `cans-upsert` reliability adoption + an ooze KPI counter fix. **Backwards-compatible.**
+Farmers / `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`.
@@ -73,7 +126,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 customer** org-structure sync again on 2026-07-09 with the exact
+fix. This crashed the **live act-gov** 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.
 
@@ -82,7 +135,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 a customer sync), and asserts
+  `::Fragment::<Name>` constant convention (the exact NameError that crashed act-gov), 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
@@ -107,7 +160,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 a customer's live tagtree / org-structure sync.
+  `addCommands`/`create`/`publish` request. Crashed the live act-gov tagtree / org-structure sync.
   Now `spread :LocationDraft` / `spread :LocationsError`, matching the gem.
 
 ### Dependencies
@@ -115,7 +168,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 a customer's live integration.
+  consumers — both crashed the live act-gov integration.
 
 ### Added
 

data/lib/eco/api/common/session/base_session.rb

@@ -36,6 +36,10 @@ module Eco::API::Common::Session
       enviro.api?(version: version)
     end
 
+    def missing_api_params(version: nil)
+      enviro.missing_api_params(version: version)
+    end
+
     def file_manager
       enviro.file_manager
     end

data/lib/eco/api/common/session/environment.rb

@@ -63,6 +63,11 @@ module Eco::API::Common::Session
       config.apis.active_api.version_available?(version)
     end
 
+    # @return [Array<Symbol>] required parameters for `version` that are missing.
+    def missing_api_params(version:)
+      config.apis.active_api.missing_api_params(version)
+    end
+
     # Shortcut to logger.
     def log(level, &block)
       return unless logger.respond_to?(:level)

data/lib/eco/api/custom/cli.rb

@@ -0,0 +1,3 @@
+# Helper class to create a custom `Cli` config
+class Eco::API::Custom::Cli < Eco::API::Common::Loaders::CliConfig
+end

data/lib/eco/api/session/config/api.rb

@@ -104,8 +104,10 @@ module Eco
             return current if current && !switch_logger
 
             unless api_params?(version)
+              missing = missing_api_params(version)
               msg  = "The api configuration for #{description} "
-              msg << "is missing data for the api version '#{self.version(version)}'"
+              msg << "is missing data for the api version '#{self.version(version)}': "
+              msg << "missing params #{missing.map {|param| ":#{param}"}.join(', ')}"
               raise ArgumentError, msg
             end
 
@@ -196,6 +198,12 @@ module Eco
             api_params?(version)
           end
 
+          # @return [Array<Symbol>] the required parameters for `version` that are
+          #   currently missing (empty when all of them are present).
+          def missing_api_params(version)
+            required_api_params(version).reject {|_param, value| value}.keys
+          end
+
           def version(value = nil)
             self.class.to_version(value || self['version'])
           end
@@ -224,15 +232,18 @@ module Eco
             when :v2
               klass.new(user_key: user_key, org_key: external_key, host: host, logger: logger)
             when :graphql
-              kargs = {
-                host:   host,
-                org_id: org_id,
-                email:  email,
-                pass:   pass
-              }
-
-              kargs.merge!({no_schema: true}) if ENV['GRAPHQL_FETCH_SCHEMA'] == "false"
-              klass.new(**kargs)
+              # NOTE: `GRAPHQL_FETCH_SCHEMA` is a documented no-op. `Ecoportal::API::GraphQL#initialize`
+              # (email:, pass:, org_id:, host:, api_key:) has never accepted a `no_schema:` keyword —
+              # it always builds its internal client with `no_schema: true` and has no public way to
+              # turn schema introspection on. Passing the unknown keyword raised ArgumentError, so the
+              # flag was worse than a no-op: setting `GRAPHQL_FETCH_SCHEMA=false` crashed api() instead
+              # of skipping a fetch that the gem's public API never performs regardless.
+              if ENV['GRAPHQL_FETCH_SCHEMA'] == "false"
+                warn "[eco-helpers] GRAPHQL_FETCH_SCHEMA is a no-op: " \
+                     "Ecoportal::API::GraphQL never fetches the schema (no_schema: true, hardcoded)."
+              end
+
+              klass.new(host: host, org_id: org_id, email: email, pass: pass)
             end.tap do |api|
               next unless api
               next if log_connection? # prevent over-logging
@@ -248,15 +259,23 @@ module Eco
 
           # Checks if the necessary parameters for a specific `API` version are available.
           def api_params?(version)
+            missing_api_params(version).empty?
+          end
+
+          # Required parameters (as `name => value` pairs) for a specific `API` version.
+          # @note `to_version` always normalises to one of the known versions below.
+          def required_api_params(version)
             case self.class.to_version(version)
             when :v0
-              internal_key && host
+              {internal_key: internal_key, host: host}
             when :v1
-              external_key && host
+              {external_key: external_key, host: host}
             when :v2
-              external_key && user_key && host
+              {external_key: external_key, user_key: user_key, host: host}
             when :graphql
-              email && pass && org_id && host
+              {email: email, pass: pass, org_id: org_id, host: host}
+            else
+              {}
             end
           end
 

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

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

@@ -0,0 +1,120 @@
+# 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/compat/ooze_redirect.rb

@@ -62,8 +62,19 @@ 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: 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).
+  # 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):
   #

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`).

data/lib/eco/api/usecases/graphql/helpers/access_logs/base/reader.rb

@@ -0,0 +1,59 @@
+module Eco::API::UseCases::GraphQL::Helpers::AccessLogs
+  module Base
+    # NATIVE reader over `currentOrganization.activityLogs` (the ActivityLogUnion behind the web
+    # "System Access Logs" page). Lazily paginates and yields `Model::ActivityLog` records.
+    #
+    # Exposes the full server filter set. Construct via `Helpers::AccessLogs::Base#access_logs`:
+    #   access_logs(source: 'web', resource_type: 'view_dashboard').each { |log| ... }
+    #   access_logs(date_filter: { from: from_iso, to: to_iso }).to_a(limit: 500)
+    class Reader
+      include Eco::API::UseCases::GraphQL::Helpers::Base::ConnectionReader
+
+      # @param graphql [Ecoportal::API::GraphQL] the active gem client.
+      # @param user_ids [Array<String>, nil]
+      # @param resource_ids [Array<String>, nil]
+      # @param filter_superusers [Boolean, nil]
+      # @param activity_type [String, nil] free-text activity type filter.
+      # @param resource_type [String, nil] ActivityLogTypesEnum value (e.g. 'view_dashboard').
+      # @param source [String, nil] SourceEnum value (e.g. 'web', 'api').
+      # @param date_filter [Hash, nil] `{ from:, to: }` (ISO8601), maps to DateRange.
+      def initialize(
+        graphql,
+        user_ids:          nil,
+        resource_ids:      nil,
+        filter_superusers: nil,
+        activity_type:     nil,
+        resource_type:     nil,
+        source:            nil,
+        date_filter:       nil
+      )
+        @graphql           = graphql
+        @user_ids          = user_ids
+        @resource_ids      = resource_ids
+        @filter_superusers = filter_superusers
+        @activity_type     = activity_type
+        @resource_type     = resource_type
+        @source            = source
+        @date_filter       = date_filter
+      end
+
+      private
+
+      def connection_query
+        @graphql.currentOrganization.activityLogs
+      end
+
+      def reader_params
+        {
+          userIds:          @user_ids,
+          resourceIds:      @resource_ids,
+          filterSuperusers: @filter_superusers,
+          activityType:     @activity_type,
+          resourceType:     @resource_type,
+          source:           @source,
+          dateFilter:       @date_filter
+        }
+      end
+    end
+  end
+end