eco-helpers 3.2.14 → 3.2.16

data/.claude/settings.json

@@ -0,0 +1,103 @@
+{
+  "permissions": {
+    "defaultMode": "auto",
+    "allowedTools": [
+      "Read"
+    ],
+    "permissionRules": [
+      {
+        "tool": "Write",
+        "pattern": "/**",
+        "action": "allow"
+      },
+      {
+        "tool": "StrReplace",
+        "pattern": "/**",
+        "action": "allow"
+      }
+    ],
+    "allow": [
+      "WebFetch(domain:anthropic.com)",
+      "WebFetch(domain:npmjs.com)",
+      "Write(.glaudeignore)",
+      "Update(.glaudeignore)",
+      "Bash(rm .ai-assistance/bridge/LOCK)",
+      "Read(.git/**)",
+      "Read(**/rubygems/**)",
+      "Write(*.md)",
+      "Edit(.ai-assistance/**)",
+      "Update(.ai-assistance/**)",
+      "Write(.ai-assistance/**)",
+      "Write(lib/**)",
+      "Write(spec/**)",
+      "Bash(git status)",
+      "Bash(git diff *)",
+      "Bash(git log *)",
+      "Bash(git add *)",
+      "Bash(git commit *)",
+      "PowerShell(git status)",
+      "PowerShell(git diff *)",
+      "PowerShell(git log *)",
+      "PowerShell(git add *)",
+      "PowerShell(git commit *)",
+      "Bash(npm test)",
+      "Bash(npm run lint)",
+      "Bash(npm run build)",
+      "Bash(vitest *)",
+      "Bash(jest *)",
+      "PowerShell(npm test)",
+      "PowerShell(npm run lint)",
+      "PowerShell(npm run build)",
+      "Bash(black .)",
+      "Bash(pytest)",
+      "Bash(python -m unittest)",
+      "Bash(ruff check *)",
+      "Bash(bundle exec rspec *)",
+      "Bash(bundle exec rubocop *)",
+      "PowerShell(pytest)",
+      "PowerShell(python -m unittest)",
+      "PowerShell(ruff check *)",
+      "PowerShell(bundle exec rspec *)",
+      "PowerShell(bundle exec rubocop *)",
+      "Bash(node .ai-assistance/scripts/token-logger.js)",
+      "Bash(node .ai-assistance/scripts/token-session-start.js)"
+    ],
+    "deny": [
+      "Read(*.env)",
+      "Read(./.env*)",
+      "Read(./secrets/**)",
+      "Bash(*cat *.env*)",
+      "Bash(*grep *.env*)",
+      "Bash(printenv*)",
+      "Bash(env)",
+      "Write(.git/*)",
+      "Edit(.git/*)",
+      "Bash(git push *)",
+      "Bash(rm -rf *)"
+    ]
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .ai-assistance/scripts/token-session-start.js 2>/dev/null || true"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .ai-assistance/scripts/token-logger.js 2>/dev/null || true"
+          }
+        ]
+      }
+    ]
+  }
+}

data/.gitignore

@@ -21,3 +21,5 @@ Gemfile.lock
 .rspec_status
 scratch.rb
 .byebug_history
+
+.ai-assistance/local/

data/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to this project will be documented in this file.
 
+## [3.2.16] - 2026-07-02
+
+APIv2→GraphQL cutover — the OozeRedirect compat layer that runs the maintained ooze integrations
+(toocs-coding, cans-upsert, supplier-documents) on GraphQL. Requires ecoportal-api-graphql >= 1.3.9.
+
+### Fixed / Changed
+
+- **OozeRedirect slimmed onto the base OozeSamples loop** — removed the `with_each_entry` /
+  `update_ooze` / `process_ooze` overrides that duplicated and silently bypassed the base loop
+  (KPIs, dedup, queue, `dry_run_feedback`). Fetches go through `ooze → apiv2.pages.get` and saves
+  through `update_oozes → update_ooze → apiv2.pages.update`; a captured `submit!`/`sign_off!` rides
+  along on the single `updatePage` via `Input::Page::Update.from_model` (reads the `_compat_*` flags).
+- **`dirty?`** also treats a pending `submit!`/`sign_off!` as dirty (so a submit-only page still saves).
+- **`OozeBaseCase#dry_run_feedback`** prints an affirmative `[dry-run] would create/update <ref>` line.
+- **`RegisterUpdateCase#enqueue`** accepts any duck-typed entry (`#dirty?` + `#as_update`), not just
+  v2 `Page`/`PageStage` — GraphQL compat pages queue correctly under OozeRedirect.
+
 ## [3.2.15] - 2026-05-xx
 
 ### Added

data/CLAUDE.md

@@ -0,0 +1,83 @@
+# CLAUDE.md — eco-helpers
+
+AI agent instructions for this repository.
+
+**Cross-cutting architecture context lives in `ecoportal-api-graphql` — see its `CLAUDE.md` and `.claude/` folder for the full dependency map, project history, and shared skills.**
+
+---
+
+## Repository Role
+
+`eco-helpers` is the **primary downstream consumer** of the EcoPortal API gem stack. It provides a scripting and automation framework for interacting with EcoPortal — CLI tooling, use-case orchestration, data transformation, and batch operations.
+
+**Position in chain:**
+```
+ecoportal-api
+ecoportal-api-v2
+ecoportal-api-graphql
+      ↓
+eco-helpers            ← THIS REPO
+```
+
+**Remote:** https://gitlab.ecoportal.co.nz/oscar/script_api_helpers.git
+
+**Gem dependencies on the stack:**
+- `ecoportal-api ~> 0.10, >= 0.10.14`
+- `ecoportal-api-v2 ~> 3.3, >= 3.3.1`
+- `ecoportal-api-graphql ~> 1.3, >= 1.3.4`
+
+---
+
+## Key Folder Layout
+
+```
+lib/eco/
+  api/                 API integration layer
+    common/            Shared helpers
+    microcases/        Fine-grained reusable operations
+    organization/      Org-level resources
+    session.rb         Session management (entry point for scripting)
+    usecases.rb        Use-case registry
+    policies.rb        Access policies
+  cli/                 CLI framework
+  cli_default/         Default CLI options, filters, people workflows
+  common/              Cross-cutting utilities
+  csv/                 CSV reading, streaming, splitting
+  data/                Data utilities (fuzzy match, hashes, locations, strings, files)
+  language/            Logging, curry, auxiliar utilities
+  assets/              Static assets (language files etc.)
+```
+
+---
+
+## Namespace
+
+`Eco::` — entirely separate namespace from `Ecoportal::`. Does not reopen upstream gem namespaces.
+
+---
+
+## Key Concerns
+
+- This gem is the **backwards-compatibility target** for all upstream gems. When `ecoportal-api-graphql` changes its public interface, check usage here first.
+- `Eco::API::Session` is the main consumer of `Ecoportal::API::GraphQL` — it's the first place to look when checking how GraphQL features are used downstream.
+- The CLI layer (`Eco::CLI`) uses Thor-style commands — changes to API interfaces may silently break CLI workflows if not tested end-to-end.
+- Many operations are batch-oriented with progress logging — error handling and partial-failure behaviour matters.
+
+---
+
+## How to Find GraphQL Usage
+
+```bash
+grep -r "GraphQL\|graphql\|ecoportal-api-graphql" lib/ --include="*.rb" -l
+```
+
+This shows which files directly use the GraphQL gem — useful when assessing impact of upstream changes.
+
+---
+
+## Running Tests
+
+```bash
+bundle install
+bundle exec rspec
+```

data/eco-helpers.gemspec

@@ -42,7 +42,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'docx',          '>= 0.8.0', '< 0.9'
   spec.add_dependency 'dotenv',        '~> 3'
   spec.add_dependency 'ecoportal-api',         '~> 0.10', '>= 0.10.14'
-  spec.add_dependency 'ecoportal-api-graphql', '~> 1.3',  '>= 1.3.4'
+  spec.add_dependency 'ecoportal-api-graphql', '~> 1.3',  '>= 1.3.9'
   spec.add_dependency 'ecoportal-api-v2',      '~> 3.3',  '>= 3.3.1'
   spec.add_dependency 'ed25519',       '~> 1.2'
   spec.add_dependency 'fast_excel',    '>= 0.5.0',  '< 0.6'

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/default/pages.rb

@@ -0,0 +1,30 @@
+module Eco
+  module API
+    class UseCases
+      class Default
+        # Namespace for CLI-integrated page use cases.
+        # These are concrete, fully functional cases exposed to all org environments.
+        #
+        # == Convention
+        # Cases here should:
+        # - Inherit from Eco::API::UseCases::GraphQL::Samples::Pages::Page::Base
+        #   (or OrgPage::Base for org-wide operations)
+        # - Be registered in the org's config/cli.rb
+        # - Be as org-agnostic as possible (accept register_id, filters via options)
+        #
+        # == Adding a new default page case
+        # 1. Create the file here: default/pages/my_case.rb
+        # 2. Inherit from the appropriate pages sample base class
+        # 3. Require it below
+        # 4. Wire CLI registration in usecases/default_cases/samples.rb or the
+        #    org's config/cli.rb
+        #
+        # == Currently
+        # No default page cases yet — add them here as common patterns emerge
+        # across org implementations.
+        module Pages
+        end
+      end
+    end
+  end
+end

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/dirty_array.rb

@@ -0,0 +1,22 @@
+module Eco::API::UseCases::GraphQL::Compat::OozeRedirect
+  # Array subclass that calls the field's setter when elements are appended,
+  # ensuring GraphQL dirty-tracking fires on `fld.people_ids << value`.
+  class DirtyArray < Array
+    def initialize(field, data)
+      @field = field
+      super(Array(data))
+    end
+
+    def <<(value)
+      super
+      @field.people_ids = to_a
+      self
+    end
+
+    def push(*values)
+      super
+      @field.people_ids = to_a
+      self
+    end
+  end
+end