ecoportal-api-graphql 1.3.13 → 1.3.16

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/skills/spec-generation/SKILL.md

@@ -1,72 +0,0 @@
-# SKILL: Spec Generation
-
-**Purpose:** Add RSpec specs that guard backwards compatibility and document expected behaviour, placed in the correct spec folder mirroring the lib/ structure.
-
----
-
-## When to Use
-
-- A change could break downstream consumers (primarily `eco-helpers`).
-- A public method or interface is being added, changed, or removed.
-- A bug is fixed — add a regression spec.
-- A new class is added that other code will depend on.
-
----
-
-## Placement Rules
-
-Spec files **mirror `lib/` structure** under `spec/`:
-
-| Code file | Spec file |
-|-----------|----------|
-| `lib/ecoportal/api/graphql/model/action.rb` | `spec/ecoportal/api/graphql/model/action_spec.rb` |
-| `lib/ecoportal/api/graphql/input/location_structure/draft.rb` | `spec/ecoportal/api/graphql/input/location_structure/draft_spec.rb` |
-
-Create the folder path if it doesn't exist.
-
----
-
-## Spec Requirements
-
-Each spec file for a changed area must have:
-
-1. A description of the class/module under test.
-2. At least one spec covering the public interface being changed.
-3. For backwards-compat specs: a comment `# backwards-compat` so they're easily searched.
-
-**Minimum spec template:**
-
-```ruby
-# frozen_string_literal: true
-
-RSpec.describe Ecoportal::API::Graphql::<ClassName> do
-  # backwards-compat
-  describe '#<method>' do
-    subject { described_class.new(<args>) }
-
-    it '<expected behaviour>' do
-      expect(subject.<method>).to <matcher>
-    end
-  end
-end
-```
-
----
-
-## Linked to Code Specs for AI
-
-Whenever a spec file is created or updated for an area, check the corresponding `.ai-assistance/code/<area>.md` doc:
-- Does it mention this class/method?
-- Does it reflect the current expected behaviour?
-
-If not — update it. This redundancy is intentional: it saves AI agents from having to parse spec files to understand expected behaviour.
-
----
-
-## Gemini Assist Integration
-
-When generating specs for a large area, you may use `gemini-assist` to:
-- Get a first-pass draft of spec cases given the source file.
-- Check for edge cases you may have missed.
-
-Always verify the generated specs run and match actual behaviour before committing.

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

@@ -1,22 +0,0 @@
-{
-  "ep-ai-standards-version": "1.5.0",
-  "applied-at": "2026-06-13",
-  "project-type": [
-    "ruby"
-  ],
-  "deferred": [],
-  "installed-components": {
-    "skills/ai-instructions": "0.0.0",
-    "skills/code-specs": "0.0.0",
-    "skills/corporate-policies": "1.0.0",
-    "skills/dep-graph": "0.0.0",
-    "skills/ep-ai-manager": "2.2.0",
-    "skills/gemini-assist": "0.0.0",
-    "skills/graphql-schema-analysis": "0.0.0",
-    "skills/project-cycle": "0.0.0",
-    "skills/project-self-docs": "0.2.0",
-    "skills/refactor": "0.0.0",
-    "skills/ruby-scripting": "0.1.0",
-    "skills/spec-generation": "0.0.0"
-  }
-}

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

@@ -1,32 +0,0 @@
-{
-  "schema_version": "1.0",
-  "project": {
-    "name": "ecoportal-api-graphql",
-    "priority": "medium",
-    "developer": "oscar@ecoportal.co.nz"
-  },
-  "weekly_quota": {
-    "total_tokens": null,
-    "target_utilization_pct": 75,
-    "reset_day": "monday"
-  },
-  "project_allocation": {
-    "priority_weights": { "high": 50, "medium": 30, "low": 20 }
-  },
-  "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"
-  ],
-
-  "auto_worker": {
-    "enabled": true,
-    "dangerously_skip_permissions": false
-  }
-}

data/.ai-assistance/version.json

@@ -1,39 +0,0 @@
-{
-  "schema": "1.0",
-  "note": "Tracks which features are installed in THIS .ai-assistance/ directory. Updated by install.sh on each deployment. Do NOT confuse with standards-version.json (ep-ai-standards compliance) — this is .ai-assistance/ infrastructure versioning.",
-
-  "installed_at": "2026-06-09",
-  "installed_from": "ep-ai-standards",
-
-  "features": {
-    "bridge_protocol": {
-      "version": "1.1.0",
-      "scripts": ["bridge-init.sh", "lock-acquire.sh", "lock-multi.sh", "lock-queue.sh", "bridge-status.sh", "check-outbox.sh"],
-      "directories": ["bridge/inbox", "bridge/outbox", "bridge/archive", "bridge/queue"],
-      "note": "v1.1.0 adds cross-repo locking (lock-multi.sh) and turn-request queue (lock-queue.sh, bridge/queue/)"
-    },
-    "token_budget": {
-      "version": "1.0.0",
-      "scripts": ["token-logger.js", "token-session-start.js", "token-report.ts"],
-      "config": "token-budget.json",
-      "hooks": ["Stop", "SessionStart"],
-      "note": "Automatic token tracking via Claude Code hooks. Requires Node.js."
-    },
-    "skills": {
-      "version": "1.0.0",
-      "directory": "skills/",
-      "note": "See skills/ for available SKILL.md files"
-    },
-    "capabilities_registry": {
-      "version": "1.0.0",
-      "directory": "capabilities/",
-      "files": ["code.md", "cowork.md", "connectors.md", "assumptions-log.md"]
-    },
-    "conventions": {
-      "version": "1.0.0",
-      "directory": "conventions/"
-    }
-  },
-
-  "how_agents_should_use_this": "Before invoking any feature, check features.<name> exists and is not null. If a feature is missing or null, the capability is not installed — do not assume it exists. Example: if features.token_budget is null, do not reference token logging commands."
-}

data/.claude/settings.json

@@ -1,150 +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)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && git status*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && git log*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && git diff*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && git show*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && git branch*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && git fetch*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && git checkout*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && git switch*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && git add*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && git commit*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && git rev-parse*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && git merge-base*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && git ls-remote*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && git stash*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && bundle exec rspec*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && bundle exec rake test*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && bundle exec rubocop*)",
-      "Bash(cd C:/ruby_scripts/git/graphlient && bundle install*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && git status*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && git log*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && git diff*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && git show*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && git branch*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && git fetch*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && git checkout*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && git switch*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && git add*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && git commit*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && git rev-parse*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && git merge-base*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && git ls-remote*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && git stash*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && bundle exec rake test*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && bundle exec rubocop*)",
-      "Bash(cd C:/ruby_scripts/git/graphql-client && bundle install*)"
-    ],
-    "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": "bash .ai-assistance/scripts/bridge-init.sh 2>/dev/null || true"
-          },
-          {
-            "type": "command",
-            "command": "node .ai-assistance/scripts/token-session-start.js 2>/dev/null || true"
-          },
-          {
-            "type": "command",
-            "command": "bash .ai-assistance/scripts/bridge-inbox-check.sh 2>/dev/null || true"
-          }
-        ]
-      }
-    ],
-    "Stop": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node .ai-assistance/scripts/token-logger.js 2>/dev/null || true"
-          },
-          {
-            "type": "command",
-            "command": "bash scripts/auto-worker-scheduler.sh 2>/dev/null || true"
-          }
-        ]
-      }
-    ]
-  }
-}

data/.env.example

@@ -1,18 +0,0 @@
-# Copy this file to .env and fill in your values.
-# .env is git-ignored — never commit real keys.
-
-# Gemini API key — get from https://aistudio.google.com/app/apikey
-GEMINI_API_KEY=your-key-here
-
-# Gemini model override — default is gemini-2.5-pro (best for large codebase analysis)
-# Cheaper/faster alternatives:
-#   gemini-2.5-flash       — good balance of speed and quality
-#   gemini-2.0-flash       — fast, lower cost
-# Run --list-models to see all available models for your key.
-# GEMINI_MODEL=gemini-2.5-flash
-
-# GitLab personal access token
-# Create at: https://gitlab.ecoportal.co.nz/-/user_settings/personal_access_tokens
-# Required scopes: read_api
-GITLAB_TOKEN=your-token-here
-GITLAB_URL=https://gitlab.ecoportal.co.nz

data/.gitattributes

@@ -1,15 +0,0 @@
-# Normalize all text files to LF in git and on checkout.
-# Claude Code writes LF; this prevents git from converting or warning.
-* text=auto eol=lf
-
-# Windows-only executables that genuinely need CRLF
-*.bat  text eol=crlf
-*.cmd  text eol=crlf
-*.ps1  text eol=crlf
-
-# Binary files — never touch line endings
-*.png  binary
-*.jpg  binary
-*.pdf  binary
-*.docx binary
-*.gem  binary

data/.gitignore

@@ -1,37 +0,0 @@
-# it's a gem, ignore the lockfile
-Gemfile.lock
-
-.env
-.ai-assistance/local_paths.md
-# build artifacts
-*.gem
-/.bundle/
-/vendor/bundle
-/spec/reports/
-/tmp/
-/pkg/
-
-# docs
-/.yardoc
-/_yardoc/
-/coverage/
-/doc/
-
-# rspec failure tracking
-.rspec_status
-scratch.rb
-tests/.byebug_history
-
-.solargraph.yml
-
-# AI assistance — local-only files
-.ai-assistance/code/dep-graph.json
-.ai-assistance/tmp/
-.ai-assistance/local/
-.ai-assistance/bridge/inbox/*.draft.md
-.ai-assistance/bridge/inbox/*.local.md
-.ai-assistance/bridge/LOCK
-.ai-assistance/bridge/STATUS
-.ai-assistance/capabilities/.env
-.ai-assistance/scripts/*.env
-.ai-assistance/scripts/node_modules/

data/.gitlab-ci.yml

@@ -1,45 +0,0 @@
-# CI pipeline for ecoportal-api-graphql
-#
-# First automated check on merge requests. Runs the RSpec suite NON-BLOCKING
-# (allow_failure: true) — it reports pass/fail status without gating merges.
-# Rationale (2026-07-10): add visibility now; tighten to a blocking gate later
-# once the suite is reliably green on a clean runner.
-#
-# Live/AI specs (tagged :live) are excluded: they need ANTHROPIC_API_KEY + network.
-# They already self-skip when the key is absent, but ~live keeps the runner off
-# that path entirely.
-#
-# NOTE: graphlient resolves from a git fork (see Gemfile); ecoportal-api / -v2 come
-# from rubygems. If a required floor (e.g. ecoportal-api-v2 >= 3.3.3) is not yet
-# published, `bundle install` may fail on the runner — because this job is
-# allow_failure, that surfaces as a warning rather than blocking the MR.
-
-workflow:
-  rules:
-    # Merge-request pipelines.
-    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
-    # Avoid a duplicate branch pipeline when an MR is already open for the branch.
-    - if: '$CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS'
-      when: never
-    # Branch pipelines (incl. main/master pushes and feature branches without an MR).
-    - if: '$CI_COMMIT_BRANCH'
-
-stages:
-  - test
-
-rspec:
-  stage: test
-  image: ruby:3.2.2
-  allow_failure: true          # non-blocking: surface failures, do not gate merges
-  variables:
-    BUNDLE_PATH: vendor/bundle  # cache installed gems between pipelines
-  cache:
-    key: "ruby-322-bundle"
-    paths:
-      - vendor/bundle
-  before_script:
-    - ruby -v
-    - gem install bundler
-    - bundle install --jobs "$(nproc)" --retry 3
-  script:
-    - bundle exec rspec --tag ~live --format progress

data/.markdownlint.json

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

data/.rspec

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