ecoportal-api-graphql 1.3.5 → 1.3.9

data/.ai-assistance/skills/project-cycle/SKILL.md

@@ -0,0 +1,177 @@
+# SKILL: Project Preparation, Maintenance & Cycle
+
+**Purpose:** Capture, organise, and track a development project from intent through completion, including upstream dependency decisions and cycle-end review.
+
+---
+
+## When to Use
+
+- A developer describes a new piece of work.
+- Picking up an existing project after a gap.
+- A cycle of changes is complete and needs a closing review.
+
+---
+
+## Folder Structure
+
+```
+.ai-assistance/projects/<project-slug>/
+  INTENT.md          What we're trying to achieve and why
+  TODO.md            Ordered task list, ticked off as done
+  DECISIONS.md       Key decisions made and why
+  UPSTREAM.md        Upstream dependency changes needed (if any)
+```
+
+Project folders are **not git-ignored** — they should be committed so other developers can pick up context.
+
+---
+
+## Starting a Project
+
+1. Ask the developer: "What are we trying to change and why?"
+2. Capture the answer in `INTENT.md` (see template below).
+3. Present it back: "Here's my understanding — does this capture it?" Iterate until confirmed.
+4. Break the intent into an ordered TODO list in `TODO.md`.
+5. If upstream deps are involved, create `UPSTREAM.md` and present options (patch, fork, new version).
+
+### INTENT.md template
+
+```markdown
+# Project: <Name>
+
+**Created:** YYYY-MM-DD
+**Status:** [active | paused | complete]
+**Branch:** feature/<slug>
+**Target branch:** main
+
+## Goal
+One paragraph: what we want to achieve.
+
+## Motivation
+Why now? What problem does this solve?
+
+## Scope
+What's in scope. What's explicitly out of scope.
+
+## Success Criteria
+How we'll know it's done.
+```
+
+---
+
+## TODO.md format
+
+```markdown
+# TODOs — <Project Name>
+
+- [ ] Task description  <!-- add detail as needed -->
+- [x] Completed task
+```
+
+Tick items off as they're completed. Never delete items — the history matters.
+
+---
+
+## DECISIONS.md format
+
+```markdown
+# Decisions — <Project Name>
+
+## [DATE] <Decision title>
+
+**Context:** What made this decision necessary.
+**Options considered:** Brief list.
+**Decision:** What was chosen.
+**Reason:** Why.
+**Consequences:** What this means going forward.
+```
+
+---
+
+## Session Start — Git Orientation (Always Do This)
+
+Before any other work, run:
+
+```bash
+# 1. Confirm current branch
+git branch --show-current
+
+# 2. Check how far ahead of target branch
+git rev-list --count main..HEAD
+
+# 3. Get a cheap summary of what's changed
+git diff main...HEAD --stat
+```
+
+Cross-reference the diff stat against the active project's `TODO.md`:
+- Changed files should map to ticked TODO items.
+- Unticked TODOs with no corresponding changed files = work not yet started.
+- Changed files with no corresponding TODO = untracked work, worth noting.
+
+If **GitKraken MCP** is connected, use it instead — it returns the same information as structured data without a bash call.
+
+If the branch in `INTENT.md` doesn't match the current branch, flag it to the developer before proceeding.
+
+---
+
+## Cycle-End Review
+
+When all TODOs are ticked:
+
+1. **Git summary:** Run `git diff main...HEAD --name-only` to get the exact file list.
+2. **Gemini review:** Pass changed files to `gemini-assist` using the `cycle_end_review.txt` prompt:
+   ```bash
+   ruby .ai-assistance/skills/gemini-assist/gemini_ask.rb \
+     --prompt-file .ai-assistance/skills/gemini-assist/prompts/cycle_end_review.txt \
+     --output .ai-assistance/projects/<slug>/gemini_review.txt \
+     --files $(git diff main...HEAD --name-only | tr '\n' ' ')
+   ```
+3. Review Gemini's output — verify each claim against actual code before acting.
+4. Propose fixes for genuine issues — confirm with developer.
+5. **If GitLab MCP is connected:** Check `get_merge_request_pipelines` to confirm CI is green.
+6. Update `INTENT.md` status to `complete`.
+7. Prompt: "Ready to open the MR / start the next project?"
+
+---
+
+## Upstream Dependency Changes
+
+If changes require modifying an upstream gem:
+
+Options (present all three to developer):
+
+1. **Local patch** — monkey-patch from this gem. Fast, messy, temporary.
+2. **Fork change** — commit to our fork (for `graphlient` or `graphql-client`). Appropriate for lasting fixes we own.
+3. **New version** — for `ecoportal-api` or `ecoportal-api-v2` (team-owned), cut a new version. For external forks, optionally contribute back upstream.
+
+Document the decision in `UPSTREAM.md` and `DECISIONS.md`.
+
+---
+
+## Session / Collaborator Setup (First Time on a Machine)
+
+When starting a session and `.ai-assistance/local_paths.md` does not exist, run this setup flow **before** any project work:
+
+1. Tell the developer: "I don't see a `local_paths.md` for your machine yet. This helps me cross-reference upstream and downstream gem code without fetching from remotes every time."
+
+2. For each dependency in the table below, ask: "Do you have `<gem>` cloned locally?"
+
+   | Gem | Remote |
+   |-----|--------|
+   | `ecoportal-api` | https://gitlab.ecoportal.co.nz/ecoportal/ecoportal-api.git |
+   | `ecoportal-api-v2` | https://gitlab.ecoportal.co.nz/oscar/ecoportal-api-v2.git |
+   | `graphlient` | https://github.com/rellampec/graphlient.git |
+   | `graphql-client` | https://github.com/rellampec/graphql-client.git |
+   | `eco-helpers` | https://gitlab.ecoportal.co.nz/oscar/script_api_helpers.git |
+
+3. For each one they have locally:
+   - In **Cowork**: ask them to connect the folder (via the folder picker), then record the confirmed path.
+   - In **Claude Code**: ask them to provide the path, or run `find ~ -name "<gemspec>" -maxdepth 6 2>/dev/null` to locate it.
+
+4. Once all available paths are collected, create `.ai-assistance/local_paths.md` from `.ai-assistance/local_paths.example.md`, filling in only the repos they confirmed.
+
+5. Also ask: "Do you have GitKraken MCP or GitLab MCP set up?" — if not, point them to `.ai-assistance/integrations/`.
+
+6. Confirm: "Done — I've saved your local paths. You can update `.ai-assistance/local_paths.md` any time if your setup changes."
+
+If a developer doesn't have a repo locally and the task requires reading it, offer: "I can fetch the relevant files from the remote — just note it'll be slower. Want me to proceed that way?"

data/.ai-assistance/skills/refactor/SKILL.md

@@ -0,0 +1,62 @@
+# SKILL: Refactor
+
+**Purpose:** Identify, log, and (with developer confirmation) apply refactoring opportunities. Never apply changes without explicit confirmation.
+
+---
+
+## When to Use
+
+- You notice a structural issue while working on something else — log it, don't fix it silently.
+- The developer asks for a refactor audit of an area.
+- A cycle-end review surfaces cleanup opportunities.
+
+---
+
+## Criteria for a Refactor Candidate
+
+Flag something when it fails one or more of:
+
+- **Understandability:** Is it clear what this does and why?
+- **Dependency tracking:** Are dependencies implicit or tangled?
+- **Separation of concerns:** Is this class/method doing more than one thing?
+- **Simplicity:** Could this be simpler without losing correctness?
+- **Alignment:** Does this match the conventions of the rest of the codebase?
+
+---
+
+## Log Format
+
+Refactoring opportunities are logged in `.ai-assistance/code/refactoring/<area>.md`.
+
+Each entry:
+
+```markdown
+## [SHORT-ID] <Title>
+
+- **File(s):** `lib/ecoportal/...`
+- **Type:** [extract_class | extract_method | rename | simplify | reorganise | other]
+- **Priority:** [high | medium | low]
+- **Status:** [open | confirmed | applied | dismissed]
+- **Identified:** YYYY-MM-DD
+
+**Observation:**
+What the issue is, concisely.
+
+**Proposed change:**
+What you'd do to fix it. High-level — not code unless it's very short.
+
+**Risk:**
+Any backwards-compat or downstream risk if applied.
+```
+
+---
+
+## Workflow
+
+1. Identify opportunity → log it in the appropriate refactoring file.
+2. Present a summary to the developer: "I've logged N refactoring opportunities in `.ai-assistance/code/refactoring/`. Want to review them?"
+3. Developer confirms which ones to apply → mark as `confirmed`.
+4. Apply one at a time, update specs if needed, mark as `applied`.
+5. If dismissed by developer → mark as `dismissed` with a brief reason.
+
+**Never apply a refactor without a `confirmed` status.**

data/.ai-assistance/skills/rubocop/SKILL.md

@@ -0,0 +1,93 @@
+# SKILL: Rubocop & Spec Runner
+
+**Purpose:** Run Rubocop on in-scope files and `rake spec`, then surface only actionable
+offences. Use this continuously as new/modified files accumulate — not deferred to the end.
+
+---
+
+## When to Use
+
+- After writing or modifying any Ruby file.
+- Before committing a change.
+- Any time TODO 6.1 says "rubocop clean on all new/modified files".
+
+---
+
+## Running Rubocop on Specific Files
+
+```bash
+bundle exec rubocop --format json <file1> [file2 ...] | \
+  ruby -rjson -e '
+    data = JSON.parse($stdin.read)
+    offences = data["files"].flat_map do |f|
+      f["offenses"].map { |o| { file: f["path"], **o.transform_keys(&:to_sym) } }
+    end
+    offences.reject! { |o| o[:cop_name].start_with?("Lint/RedundantCopDisableDirective") }
+    if offences.empty?
+      puts "No offences."
+    else
+      offences.each do |o|
+        puts "#{o[:file]}:#{o[:location][:line]}:#{o[:location][:column]} " \
+             "[#{o[:severity]}] #{o[:cop_name]} — #{o[:message]}"
+      end
+      puts "\n#{offences.size} offence(s)."
+    end
+  '
+```
+
+**Key flags:**
+- `--format json` — machine-parseable output, avoids ANSI noise.
+- No `--autocorrect` here — apply corrections explicitly when needed (see below).
+
+---
+
+## Auto-correcting Safe Offences
+
+```bash
+bundle exec rubocop --autocorrect --format json <file1> [file2 ...]
+```
+
+Only use `--autocorrect` (not `--autocorrect-all`) to limit to safe cops.
+Always re-read the file after correction and verify the diff is sensible.
+
+---
+
+## Running the Full Suite
+
+```bash
+bundle exec rake spec
+```
+
+Run after a meaningful unit of work is complete. Failures must be resolved before moving on.
+
+---
+
+## Workflow
+
+1. Write or edit a file.
+2. Run rubocop on that file (command above).
+3. Fix all reported offences (except those covered by existing `# rubocop:disable` comments — the
+   disable is intentional; do not remove it).
+4. Re-run rubocop to confirm zero offences.
+5. When a group of files is complete, run `rake spec` to confirm no regressions.
+
+---
+
+## Rules
+
+- **Do not second-guess `rubocop:disable` inline comments.** They are intentional suppressions
+  chosen by the developer or a previous agent. Leave them in place.
+- **Do not add new `rubocop:disable` comments** unless the developer explicitly instructs it.
+  Fix the offence instead.
+- **Surface every remaining offence** — do not filter by severity. Let the developer decide
+  what to defer.
+- `Lint/RedundantCopDisableDirective` offences are suppressed in the output above because
+  they appear when a disable comment is no longer needed; rubocop handles their cleanup itself.
+
+---
+
+## Linked TODOs
+
+- **6.0** — This skill (done once built).
+- **6.1** — Run continuously on all new/modified files throughout the migration.
+- **6.2** — `rake spec` coverage for `HttpClient#execute`, `Fragment.assemble`, end-to-end query.

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

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

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

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

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

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