eco-helpers 3.2.18 → 3.3.0

data/.ai-assistance/skills/ruby-scripting/SKILL.md

@@ -1,215 +0,0 @@
----
-name: ruby-scripting
-version: 0.1.0
-description: >
-  AI coding assistant guidelines for internal Ruby scripts that consume ecoPortal's
-  Ruby gem stack (ecoportal-api-graphql, ecoportal-api, eco-helpers). Covers gem
-  authentication, GraphQL query patterns, mutation patterns, error handling, and
-  cross-platform script conventions (Windows/WSL/macOS/Linux).
-triggers:
-  - ruby script
-  - internal script
-  - ecoportal-api
-  - graphql query
-  - ruby-scripting
-  - write a ruby script
-applicable_to:
-  - ruby
----
-
-# SKILL: Ruby Scripting (ecoPortal Internal)
-
-**Purpose:** Guidelines for AI-assisted authoring of internal Ruby scripts that use the ecoPortal gem stack. These scripts run internally — no customer access; Ruby is not a customer-facing language at ecoPortal.
-
----
-
-## When to Use
-
-- Writing a new script that queries or mutates ecoPortal data via the GraphQL API
-- Debugging or extending an existing script in `ruby_scripts/` or similar
-- Any task involving `ecoportal-api-graphql`, `ecoportal-api`, or `eco-helpers`
-
----
-
-## Gem Stack
-
-```
-ecoportal-api-graphql   ← GraphQL client layer (mutations, queries, models)
-       ↑
-ecoportal-api / ecoportal-api-v2   ← REST API + base model infrastructure
-       ↑
-eco-helpers             ← Utility helpers (pagination, bulk ops, etc.)
-```
-
-**Before writing any API call**, check:
-1. Does `eco-helpers` already have a helper for this operation? (It often does.)
-2. Does `ecoportal-api-graphql` already have a model/mutation class?
-3. Read `.ai-assistance/code/dependencies.md` in `ecoportal-api-graphql` for local paths.
-
----
-
-## Authentication
-
-```ruby
-require 'ecoportal/api'
-
-api = Ecoportal::API::V2.new(
-  key: ENV.fetch('EP_API_KEY'),
-  host: ENV.fetch('EP_API_HOST', 'live.ecoportal.com')
-)
-```
-
-Always use `ENV.fetch` (not `ENV[]`) — raises on missing key rather than silently using nil.
-Store credentials in `.env` (gitignored). Never hardcode.
-
----
-
-## GraphQL Query Pattern
-
-```ruby
-# Read models via GraphQL
-result = api.graphql.query do |q|
-  q.current_organization do |org|
-    org.name
-    org.users(first: 50) do |conn|
-      conn.nodes do |user|
-        user.id
-        user.email
-      end
-    end
-  end
-end
-
-# Check for errors before using data
-raise result.errors.map(&:message).join(', ') if result.errors.any?
-users = result.data.current_organization.users.nodes
-```
-
-**Pagination:** use `eco-helpers` pagination helpers for large result sets rather than
-writing manual cursor loops.
-
----
-
-## Mutation Pattern
-
-```ruby
-# Mutations require patchVer for types that use optimistic locking
-# Always fetch before mutate for those types
-current = api.graphql.query { ... }.data.some_item
-result = api.graphql.mutate do |m|
-  m.update_item(input: {
-    id: current.id,
-    patch_ver: current.patch_ver,   # required for patchVer types
-    name: "New Name"
-  }) do |payload|
-    payload.item { |i| i.id; i.name }
-    payload.errors { |e| e.message; e.path }
-  end
-end
-
-raise result.errors.map(&:message).join(', ') if result.errors.any?
-raise result.data.update_item.errors.map(&:message).join(', ') \
-  if result.data.update_item.errors.any?
-```
-
-**patchVer rule:** any schema type with a `patchVer` field requires reading current value
-before any update. See `graphql-schema-analysis` skill for detection.
-
----
-
-## Cross-Platform Script Conventions
-
-These scripts run on developer machines (Windows/WSL, macOS, Linux CI):
-
-```ruby
-# ✅ Safe: Ruby's File/Pathname handles separators cross-platform
-require 'pathname'
-base = Pathname.new(File.dirname(__FILE__))
-data_file = base / 'data' / 'input.json'
-
-# ❌ Unsafe: hardcoded separators, or shell assumptions
-data_file = "#{__dir__}\\data\\input.json"   # breaks on Linux
-`cat #{data_file}`                            # assumes Unix shell
-```
-
-**Environment detection:**
-```ruby
-WINDOWS = Gem.win_platform?
-# Use for platform-specific paths only — prefer Pathname for everything else
-```
-
-**Output:** use `$stdout.puts` not `print` for script output. Use `$stderr.puts` for
-errors. This allows the script to be piped and combined cleanly.
-
-**Exit codes:** always `exit 0` on success, `exit 1` on error. Never let an unhandled
-exception be the exit mechanism in production scripts.
-
----
-
-## Error Handling
-
-```ruby
-begin
-  # API calls here
-rescue Ecoportal::API::Errors::ApiError => e
-  $stderr.puts "API error: #{e.message} (status: #{e.status})"
-  exit 1
-rescue => e
-  $stderr.puts "Unexpected error: #{e.class}: #{e.message}"
-  $stderr.puts e.backtrace.first(5).join("\n")
-  exit 1
-end
-```
-
----
-
-## Script Structure Template
-
-```ruby
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-#
-# Script: <name>.rb
-# Purpose: <one sentence>
-# Usage: ruby <name>.rb [options]
-# Dependencies: ecoportal-api-graphql, dotenv
-#
-# Run from repo root: bundle exec ruby scripts/<name>.rb
-
-require 'bundler/setup'
-require 'dotenv/load'
-require 'ecoportal/api'
-# ... other requires
-
-api = Ecoportal::API::V2.new(
-  key: ENV.fetch('EP_API_KEY'),
-  host: ENV.fetch('EP_API_HOST', 'live.ecoportal.com')
-)
-
-begin
-  # main logic here
-rescue => e
-  $stderr.puts "Error: #{e.class}: #{e.message}"
-  exit 1
-end
-```
-
----
-
-## What NOT to do
-
-- Don't write raw HTTP calls to the EcoPortal API — use the gem stack
-- Don't paginate manually — use `eco-helpers` pagination
-- Don't hardcode API keys, hosts, or org identifiers
-- Don't use `pp` or `binding.pry` in committed scripts — use structured logging
-- Don't assume a Unix shell — use Ruby cross-platform file handling
-
----
-
-## v0.1.0 limitations
-
-This skill covers general patterns. For area-specific details (specific GraphQL models,
-available mutation inputs, schema patterns), consult:
-- `ecoportal-api-graphql/.ai-assistance/code/` for code specs
-- `ecoportal-api-graphql/.ai-assistance/skills/graphql-schema-analysis/SKILL.md`
-- Live schema introspection (see graphql-schema-analysis skill)

data/.ai-assistance/standards-version.json

@@ -1,10 +0,0 @@
-{
-  "ep-ai-standards-version": "1.5.0",
-  "applied-at": "2026-06-13",
-  "project-type": ["ruby"],
-  "deferred": [],
-  "installed-components": {
-    "skills/ep-ai-manager": "2.1.0",
-    "skills/ruby-scripting": "0.1.0"
-  }
-}

data/.ai-assistance/token-budget.json

@@ -1,39 +0,0 @@
-{
-  "schema_version": "1.0",
-  "project": {
-    "name": "eco-helpers",
-    "priority": "low",
-    "developer": "oscar@ecoportal.co.nz"
-  },
-  "weekly_quota": {
-    "total_tokens": null,
-    "target_utilization_pct": 75,
-    "reset_day": "monday",
-    "note": "total_tokens: null means track actuals without a hard cap. Set to e.g. 1000000 to enforce a budget."
-  },
-  "project_allocation": {
-    "priority_weights": {
-      "high": 50,
-      "medium": 30,
-      "low": 20
-    },
-    "note": "A 'high' priority project gets ~50% of the weekly budget; 'medium' gets ~30%; 'low' gets ~20%. These are soft targets — the system warns, not blocks."
-  },
-  "session_logging": {
-    "enabled": true,
-    "log_dir": ".ai-assistance/local/kpi",
-    "warn_at_pct": 80,
-    "prompt_category_at_stop": true
-  },
-  "task_categories": [
-    "coding",
-    "bug_fixing",
-    "bug_prevention",
-    "documentation",
-    "communication",
-    "post_release",
-    "troubleshooting",
-    "integration_delivery",
-    "skills_development"
-  ]
-}

data/.claude/settings.json

@@ -1,103 +0,0 @@
-{
-  "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

@@ -1,25 +0,0 @@
-# it's a gem, ignore the lockfile
-Gemfile.lock
-
-# build artifacts
-*.gem
-/.bundle
-/.vscode
-.solargraph.yml
-/vendor/bundle
-/spec/reports/
-/tmp/
-/pkg/
-
-# docs
-/.yardoc
-/_yardoc/
-/coverage/
-/doc/
-
-# rspec failure tracking
-.rspec_status
-scratch.rb
-.byebug_history
-
-.ai-assistance/local/

data/.idea/.gitignore

@@ -1,10 +0,0 @@
-# Default ignored files
-/shelf/
-/workspace.xml
-# Editor-based HTTP Client requests
-/httpRequests/
-# Datasource local storage ignored files
-/dataSources/
-/dataSources.local.xml
-# jetbrains IDE
-.idea

data/.markdownlint.json

@@ -1,4 +0,0 @@
-{
-  "MD013": false,
-  "MD024": false
-}

data/.rspec

@@ -1,3 +0,0 @@
---format documentation
---color
---require spec_helper

data/.rubocop.yml

@@ -1,103 +0,0 @@
-AllCops:
-  TargetRubyVersion: 3.2
-  Exclude:
-    - 'config/routes.rb'
-  NewCops: enable
-
-Metrics/ClassLength:
-  Max: 500
-Metrics/ModuleLength:
-  Max: 300
-Metrics/MethodLength:
-  Max: 50
-Metrics/AbcSize:
-  Max: 30
-Metrics/ParameterLists:
-  Max: 5
-  CountKeywordArgs: false
-Metrics/BlockLength:
-  CountAsOne: ['array', 'heredoc', 'method_call']
-  Max: 50
-Metrics/CyclomaticComplexity:
-  Max: 30
-Metrics/PerceivedComplexity:
-  Max: 30
-
-Style/AccessorGrouping:
-  Enabled: false
-Style/ConditionalAssignment:
-  Enabled: false
-Style/BlockDelimiters:
-  BracesRequiredMethods: ['log']
-  AllowedPatterns: ['proc', 'new']
-Style/HashSyntax:
-  EnforcedShorthandSyntax: either
-  EnforcedStyle: no_mixed_keys
-
-Style/ArgumentsForwarding:
-  UseAnonymousForwarding: false
-Style/ClassAndModuleChildren:
-  Enabled: false
-Style/FrozenStringLiteralComment:
-  Enabled: false
-Style/StringLiterals:
-  Enabled: false
-Style/StringLiteralsInInterpolation:
-  Enabled: false
-Style/Documentation:
-  Enabled: false
-Style/CommentedKeyword:
-  Enabled: false
-Style/MultilineBlockChain:
-  Enabled: false
-Style/AndOr:
-  Enabled: false
-Style/Alias:
-  EnforcedStyle: prefer_alias_method
-Style/FetchEnvVar:
-  Enabled: false
-Style/RegexpLiteral:
-  EnforcedStyle: mixed
-  AllowInnerSlashes: true
-
-Layout/HashAlignment:
-  EnforcedColonStyle: table
-  EnforcedHashRocketStyle: table
-Layout/LeadingCommentSpace:
-  Enabled: false
-  AllowGemfileRubyComment: true
-Layout/ParameterAlignment:
-  Enabled: false
-Layout/MultilineMethodDefinitionBraceLayout:
-  EnforcedStyle: symmetrical
-Layout/LineLength:
-  Enabled: true
-Layout/SpaceInsideHashLiteralBraces:
-  Enabled: false
-Layout/SpaceInsideBlockBraces:
-  Enabled: false
-Layout/SpaceAroundOperators:
-  Enabled: false
-Layout/ExtraSpacing:
-  AllowForAlignment: true
-  AllowBeforeTrailingComments: true
-Layout/AccessModifierIndentation:
-  EnforcedStyle: indent
-Layout/DotPosition:
-  EnforcedStyle: trailing
-Layout/MultilineMethodCallIndentation:
-  EnforcedStyle: indented
-Layout/FirstHashElementIndentation:
-  Enabled: false
-Layout/EmptyLineAfterGuardClause:
-  Enabled: false
-
-Naming/VariableNumber:
-  EnforcedStyle: snake_case
-  CheckSymbols: false
-Naming/MethodParameterName:
-  AllowedNames: ['x', 'y', 'i', 'j', 'id', 'io', 'to']
-Naming/RescuedExceptionsVariableName:
-  Enabled: false
-Naming/BlockForwarding:
-  Enabled: false

data/.ruby-version

@@ -1 +0,0 @@
-3.2.2

data/.yardopts

@@ -1,10 +0,0 @@
---readme README.md
---charset utf-8
---markup-provider=redcarpet
---markup=markdown
---no-private
---output-dir ./doc
-'lib/**/*.rb'
-CHANGELOG.md
--
-LICENSE

data/CLAUDE.md

@@ -1,83 +0,0 @@
-# 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/Gemfile

@@ -1,8 +0,0 @@
-source "https://rubygems.org"
-
-git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
-
-# Specify your gem's dependencies in eco-helpers.gemspec
-gemspec
-
-# gem 'rubocop-rake', require: false

data/Rakefile

@@ -1,38 +0,0 @@
-require 'bundler/gem_tasks'
-require 'rspec/core/rake_task'
-require 'rubocop/rake_task'
-require 'yard'
-require 'redcarpet'
-
-desc "run the specs"
-RSpec::Core::RakeTask.new(:spec)
-
-desc "run rspec showing backtrace"
-RSpec::Core::RakeTask.new(:spec_trace) do |task|
-  task.rspec_opts = ['--backtrace']
-end
-task(rspec_trace: :spec_trace)
-
-desc "run rspec stopping on first fail, and show backtrace"
-RSpec::Core::RakeTask.new(:spec_fast) do |task|
-  task.rspec_opts = ['--fail-fast', '--backtrace']
-end
-task(rspec_fast: :spec_fast)
-
-desc "run rubocop diaplying cop names"
-RuboCop::RakeTask.new(:rubocop) do |t|
-  t.options = ['--display-cop-names']
-end
-
-# default task name is yard
-desc "Yard: generate all the documentation"
-YARD::Rake::YardocTask.new(:doc) do |t|
-  #t.files = ['lib/**/*.rb']
-end
-
-desc "default task: runs rubocop and rspec"
-task :default do
-  Rake::Task[:rubocop].invoke
-ensure
-  Rake::Task[:spec].invoke
-end