eco-helpers 3.2.13 → 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,7 +2,24 @@
 
 All notable changes to this project will be documented in this file.
 
-## [3.2.14] - 2026-04-xx
+## [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
 
@@ -10,6 +27,17 @@ All notable changes to this project will be documented in this file.
 
 ### Fixed
 
+## [3.2.14] - 2026-05-22
+
+### Added
+
+- `track-files` case
+- `add-page-id` case
+
+### Changed
+
+- **improvement**: added `-format` argument to `-group-csv` to output a `jsonl` **custom** file.
+
 ## [3.2.13] - 2026-04-15
 
 ### 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/default/utils/add_page_id_case.rb

@@ -0,0 +1,273 @@
+# @note you might add a `filter` method
+#
+#      def filter
+#        @filter ||= proc do |row, _r_idx|
+#          next true
+#          next true unless (ref_id = row[pivot_column(row)])
+#          next false if excluded_ref_id?(ref_id)
+#
+#          true
+#        end
+#      end
+#
+class Eco::API::UseCases::Default::Utils::AddPageId < Eco::API::Custom::UseCase
+  name 'add-page-id'
+  type :other
+
+  require_relative 'cli/add_page_id_cli'
+
+  PIVOT_FIELD = [
+    'ref_id'
+  ].freeze
+
+  PAGE_ID          = 'page_id'.freeze
+  EXCLUDED_REF_IDS = %w[].freeze
+
+  def main(*_args)
+    if simulate?
+      count = Eco::CSV.count(input_file)
+      log(:info) { "CSV '#{input_file}' has #{count} rows." }
+    else
+      generate_file(&filter)
+    end
+  end
+
+  private
+
+  attr_reader :headers, :headers_rest
+
+  def filter
+    nil
+  end
+
+  def excluded_ref_id?(ref_id)
+    self.class::EXCLUDED_REF_IDS.include?(ref_id)
+  end
+
+  def generate_file # rubocop:disable Metrics/AbcSize
+    idx           = -1
+    row_count     = 0
+    headers_added = false
+
+    CSV.open(output_filename, 'wb') do |csv|
+      puts "\n"
+
+      Eco::CSV.foreach(input_file, headers: true, skip_blanks: true) do |row|
+        idx += 1
+
+        next unless !block_given? || yield(row, idx)
+
+        unless headers_added
+          headers!(row)
+          require_pivot_field!(row, file: input_file)
+
+          csv           << headers
+          headers_added = true
+        end
+
+        unless (pivot_value = row[pivot_field])
+          msg  = "Row #{idx} doesn't have value for pivot field '#{pivot_field}'"
+          msg << ". Skipping (discarded) ..."
+          log(:warn) { msg }
+          next
+        end
+
+        unless (page_id = input_maps[pivot_value])
+          warn_unknown_mapping_reference!(pivot_value)
+          next
+        end
+
+        row_count += 1
+
+        if (row_count % 500).zero?
+          print "... Mapped #{row_count} rows          \r"
+          $stdout.flush
+        end
+
+        values     = [page_id, pivot_value]
+        oth_values = row.values_at(*headers_rest)
+        values.concat(oth_values) unless headers_rest.empty?
+
+        csv << values
+      end
+    end
+  ensure
+    msg = "Generated file '#{output_filename}' with #{row_count} rows (out of #{idx})."
+    log(:info) { msg } unless simulate?
+  end
+
+  def warn_unknown_mapping_reference!(ref_id)
+    return if unknown.include?(ref_id)
+
+    unknown << ref_id
+    msg  = "Could not map '#{pivot_field}' '#{ref_id}' to a '#{page_id_field}'"
+    msg << ". Skipping (discarded) ..."
+
+    log(:warn) { msg }
+  end
+
+  def unknown
+    @unknown ||= []
+  end
+
+  def headers!(row)
+    return if instance_variable_defined?(:@headers)
+
+    @headers_rest = row.headers - base_out_header(row)
+    @headers      = [*base_out_header, *headers_rest]
+  end
+
+  def base_out_header(row = nil)
+    @base_out_header ||= [page_id_field, pivot_field(row)] # space: :output
+  end
+
+  def input_maps
+    return @input_maps if instance_variable_defined?(:@input_maps)
+
+    @input_maps = {}
+    idx = 0
+
+    Eco::CSV.foreach(input_maps_file, headers: true) do |row|
+      idx += 1
+
+      if (idx % 500).zero?
+        print "... Creating mappings table (#{idx} done)          \r"
+        $stdout.flush
+      end
+
+      require_pivot_field!(row, space: :maps, file: input_maps_file)
+      require_page_id_field!(row, file: input_maps_file)
+
+      ref_id  = row[pivot_field(space: :maps)]
+      page_id = row[page_id_field(space: :maps)]
+
+      @input_maps[ref_id] = page_id
+    end
+
+    @input_maps
+  end
+
+  def input_maps_file
+    options.dig(:input, :maps).tap do |file|
+      next if file && File.exist?(file)
+
+      log(:error) {
+        msg = "You must specify an existing maps file with the option '-maps-file'"
+        msg << ".\n  * File: '#{file}' does not exist" unless file.nil?
+        msg
+      }
+      exit 1
+    end
+  end
+
+  def output_filename
+    return nil unless input_name
+
+    File.join(
+      input_dir,
+      "#{input_name}_mapped#{input_ext}"
+    )
+  end
+
+  def input_name
+    @input_name ||= File.basename(
+      input_basename,
+      input_ext
+    )
+  end
+
+  def input_ext
+    @input_ext ||= input_basename.split('.')[1..].join('.').then do |name|
+      ".#{name}"
+    end
+  end
+
+  def input_basename
+    @input_basename ||= File.basename(input_full_filename)
+  end
+
+  def input_dir
+    @input_dir = File.dirname(input_full_filename)
+  end
+
+  def input_full_filename
+    @input_full_filename ||= File.expand_path(input_file)
+  end
+
+  def input_file
+    options.dig(:input, :file)
+  end
+
+  def require_pivot_field!(row, file:, space: :input)
+    return true if row.key?(pivot_field(row, space: space))
+
+    msg = "Pivot field '#{pivot_field}' missing in header of file '#{file}'"
+    log(:error) { msg }
+    raise msg
+  end
+
+  def require_page_id_field!(row, file:)
+    return true if row.key?(page_id_field(space: :maps))
+
+    msg = "Page ID field '#{page_id_field(space: :maps)}' missing in header of file '#{file}'"
+    log(:error) { msg }
+    raise msg
+  end
+
+  def pivot_field(row = nil, space: :input)
+    @pivot_field ||= {}
+    return @pivot_field[space] if @pivot_field.key?(space)
+
+    @pivot_field[space] ||= pivot_fields(space: space).select do |name|
+      row.key?(name)
+    end.then do |sel|
+      next sel.first if sel.one?
+
+      msg = "Could not find any column named: #{pivot_fields.join(', ')}"
+      msg = "Multiple pivot columns: #{sel.join(', ')}" if sel.any?
+
+      log(:error) { msg }
+      raise msg
+    end.tap do |col|
+      log(:info) { "Using header '#{col}' as pivot column." }
+    end
+  end
+
+  def pivot_fields(space: :input)
+    @pivot_fields ||= {}
+    return @pivot_fields[space] if @pivot_fields.key?(space)
+
+    return (@pivot_fields[space] = [opts_pivot]) if opts_pivot && space == :input
+
+    unless self.class.const_defined?(:PIVOT_FIELD)
+      msg = "(#{self.class}) You must define PIVOT_FIELD constant"
+      log(:error) { msg }
+      raise msg
+    end
+
+    @pivot_fields[space] = self.class::PIVOT_FIELD.dup
+  end
+
+  def page_id_field(space: :output)
+    @page_id_field = {}
+    return @page_id_field[space] if @page_id_field.key?(space)
+
+    return (@page_id_field[space] = opts_page_id) if opts_page_id && space == :output
+
+    unless self.class.const_defined?(:PAGE_ID)
+      msg = "(#{self.class}) You must define PAGE_ID field constant"
+      log(:error) { msg }
+      raise msg
+    end
+
+    @page_id_field[space] = self.class::PAGE_ID
+  end
+
+  def opts_pivot
+    options.dig(:input, :pivot_field)
+  end
+
+  def opts_page_id
+    options.dig(:input, :page_id)
+  end
+end

data/lib/eco/api/usecases/default/utils/cli/add_page_id_cli.rb

@@ -0,0 +1,29 @@
+class Eco::API::UseCases::Default::Utils::AddPageId
+  class Cli < Eco::API::UseCases::Cli
+    desc 'Adds the page_id column based on mappings onto -pivot'
+
+    callback do |_session, options, _usecase|
+      if (file = SCR.get_file(cli_name, required: true, should_exist: true))
+        options.deep_merge!(input: {file: file})
+      end
+    end
+
+    add_option('-maps-file', 'Source file with he mappings') do |options|
+      if (file = SCR.get_file('-maps-file', required: true, should_exist: true))
+        options.deep_merge!(input: {maps: file})
+      end
+    end
+
+    add_option('-pivot', 'The column that should be used to pivot') do |options|
+      if (file = SCR.get_arg("-pivot", with_param: true))
+        options.deep_merge!(input: {pivot_field: file})
+      end
+    end
+
+    add_option('-page-id', 'The column that should be used to dump the id') do |options|
+      if (file = SCR.get_arg("-page-id", with_param: true))
+        options.deep_merge!(input: {page_id: file})
+      end
+    end
+  end
+end

data/lib/eco/api/usecases/default/utils/cli/group_csv_cli.rb

@@ -22,5 +22,10 @@ class Eco::API::UseCases::Default::Utils::GroupCsv
         options.deep_merge!(input: {group_by_field: file})
       end
     end
+
+    add_option('-format', 'Kind of extract (csv - default | jsonl') do |options|
+      format = SCR.get_arg('-format', with_param: true)
+      options.deep_merge!(output: {format: format})
+    end
   end
 end

data/lib/eco/api/usecases/default/utils/cli/track_files_cli.rb

@@ -0,0 +1,16 @@
+class Eco::API::UseCases::Default::Utils::TrackFiles
+  class Cli < Eco::API::UseCases::Cli
+    desc 'Tracks the files of a folder in a CSV'
+
+    callback do |_session, options, _usecase|
+      if (folder = SCR.get_file(cli_name, required: true))
+        options.deep_merge!(input: {folder: folder})
+      end
+    end
+
+    add_option("-s3-path", "Relative subpath from the S3 uploads folder.") do |options|
+      path = SCR.get_arg("-s3-path", with_param: true)
+      options.deep_merge!(output: {s3_path: path})
+    end
+  end
+end