ecoportal-api-graphql 1.3.5 → 1.3.9

data/CLAUDE.md

@@ -0,0 +1,232 @@
+# CLAUDE.md — ecoportal-api-graphql
+
+AI agent instructions for working in this repository. Read this before touching any code.
+
+---
+
+## Read these first — every session
+
+```
+docs/worklog.md                          ← current state, blockers, open questions
+.ai-assistance/projects/<slug>/TODO.md   ← active project task list
+.ai-assistance/local/paths.json          ← local paths to sibling repos (gitignored — machine-specific)
+.ai-assistance/bridge/CLAUDE.md          ← bridge protocol: format, lifecycle, cross-repo requests
+```
+
+---
+
+## Repository Role
+
+`ecoportal-api-graphql` is a **Ruby gem** that provides a GraphQL client layer on top of EcoPortal's REST API infrastructure. It sits between the upstream API gems and downstream consumer code.
+
+**Dependency chain:**
+
+```
+[graphql-ruby]  [graphql-client]  [graphlient]  (upstream, external/forked)
+      ↓
+ecoportal-api  /  ecoportal-api-v2              (upstream, team-managed)
+      ↓
+ecoportal-api-graphql                           ← THIS REPO
+      ↓
+eco-helpers                                     (downstream, team-managed)
+```
+
+Backwards compatibility with `eco-helpers` must be preserved unless explicitly broken by the developer.
+
+**For full dependency details — local paths, remotes, fork relationships, and access notes — see `.ai-assistance/code/dependencies.md`.**
+
+---
+
+## Key Folder Layout
+
+```
+lib/ecoportal/api/graphql/       Main gem code
+  base/                          Base model classes (data structures)
+  builder/                       Builder pattern classes
+  concerns/                      Shared modules (mixins)
+  connection/                    GraphQL connection types
+  error/                         Error classes
+  fragment/                      GraphQL fragment definitions
+  helpers/                       Utility helpers
+  input/                         Mutation input objects
+  interface/                     GraphQL interface types
+  logic/                         Query/mutation execution logic
+  model/                         Domain model classes
+  mutation/                      Mutation definitions
+  payload/                       Mutation response payloads
+  query/                         Query definitions
+
+lib/ecoportal/api/common/graphql/ Shared/common GraphQL utilities
+
+spec/ecoportal/                  RSpec specs (mirrors lib/ structure)
+tests/                           Manual integration test scripts
+.ai-assistance/                         AI agent resources (see below)
+```
+
+---
+
+## .ai-assistance/ Resources
+
+All AI agent tooling lives under `.ai-assistance/`. **Read relevant docs before analysing code.**
+
+| Path | Purpose |
+|------|---------|
+| `.ai-assistance/skills/` | Skill definitions — see each `SKILL.md` |
+| `.ai-assistance/code/` | Code specs for AI (per-area markdown docs) |
+| `.ai-assistance/code/dependencies.md` | Full dependency map with local paths and remote URLs |
+| `.ai-assistance/code/refactoring/` | Refactoring opportunity log |
+| `.ai-assistance/projects/` | Project intent, TODOs, and decision logs |
+| `.ai-assistance/integrations/` | Optional dev tool integrations (GitLab MCP, GitKraken MCP, local git) |
+
+### Commit authorship
+
+**Default: developer only.** Do not add `Co-Authored-By: Claude ...` to commits unless
+the developer explicitly requests it for a specific commit.
+
+### Available Skills
+
+| Skill | SKILL.md | Purpose |
+|-------|----------|---------|
+| `ep-ai-manager` | `.ai-assistance/skills/ep-ai-manager/SKILL.md` | Check alignment with ep-ai-standards |
+| `ruby-scripting` | `.ai-assistance/skills/ruby-scripting/SKILL.md` | Guidelines for scripts using ecoportal gem stack |
+| `gemini-assist` | `.ai-assistance/skills/gemini-assist/SKILL.md` | Offload large-context tasks to Gemini |
+| `ai-instructions` | `.ai-assistance/skills/ai-instructions/SKILL.md` | Manage CLAUDE.md and skill files |
+| `code-specs` | `.ai-assistance/skills/code-specs/SKILL.md` | Write/update AI-readable code documentation |
+| `spec-generation` | `.ai-assistance/skills/spec-generation/SKILL.md` | Generate RSpec specs for backwards-compat |
+| `refactor` | `.ai-assistance/skills/refactor/SKILL.md` | Identify and log refactoring opportunities |
+| `project-cycle` | `.ai-assistance/skills/project-cycle/SKILL.md` | Project planning, TODOs, decisions |
+
+---
+
+## Permissions & Autonomy
+
+Read `.ai-assistance/conventions/permission-guidance.md` to understand:
+- Which operations require confirmation vs. proceed autonomously (autonomy zones)
+- When and how to suggest new allowlist entries to the developer
+- Project vs. global scope for `settings.json` rules
+- How to handle compound `cd path && cmd` patterns in sibling repos
+
+---
+
+## Running Tests
+
+```bash
+# Full suite
+bundle exec rspec
+
+# Single file
+bundle exec rspec spec/ecoportal/api/graphql/input/search_conf_spec.rb
+
+# Live AI tests (requires ANTHROPIC_API_KEY — loaded automatically from .env)
+bundle exec rspec spec/ecoportal/api/graphql/input/search_conf/ai_generator_spec.rb --tag live
+```
+
+**Live tests:** `.env` is loaded via `dotenv` in `spec_helper.rb`. Add `ANTHROPIC_API_KEY=sk-ant-...` to `.env` (gitignored) — no need to export to shell.
+
+---
+
+## Conventions
+
+- **Namespace:** `Ecoportal::API::GraphQL` — capital G, Q, L, matching the `class GraphQL` declaration in `lib/ecoportal/api/graphql.rb`
+- **File/class mirroring:** File path mirrors the class namespace exactly.
+- **Spec mirroring:** Spec files mirror `lib/` structure under `spec/`.
+- **Code spec docs:** For every area analysed, a corresponding `.ai-assistance/code/<area>.md` should exist or be created/updated.
+- **No silent breaking changes:** Any change that affects the public interface of this gem must be noted in the active project's DECISIONS log and confirmed with the developer.
+- **Gemini responses must be verified** before applying — Gemini hallucinates details. Always cross-check against actual code.
+- **Rubocop:** All generated Ruby code must comply with `.rubocop.yml`. Run `bundle exec rubocop <file>` to verify.
+
+---
+
+## First Session on a New Machine
+
+If `.ai-assistance/local_paths.md` does not exist, run the collaborator setup flow from the `project-cycle` skill **before** any other work. In short:
+
+- Ask which upstream/downstream repos the developer has cloned locally.
+- In Cowork: offer to connect each folder. In Claude Code: ask for the path or locate it via shell.
+- Create `.ai-assistance/local_paths.md` from `.ai-assistance/local_paths.example.md` with their confirmed paths.
+- If a repo isn't available locally, offer to fetch what's needed from the remote URL instead.
+
+---
+
+## Before Starting Any Task
+
+1. Check `.ai-assistance/local_paths.md` — if missing, run First Session setup above before proceeding.
+2. Check `.ai-assistance/projects/` for an active project file.
+3. Check `.ai-assistance/code/` for an existing spec doc covering the area you'll work in.
+4. Check `.ai-assistance/code/dependencies.md` if the task touches upstream or downstream gems.
+5. Check `.ai-assistance/code/refactoring/` for logged opportunities relevant to the area.
+6. If none of the above exist for your area — create them as you go (see `code-specs` skill).
+
+## Before Making Working Tree Changes (Claude Code only)
+
+If you are about to modify files outside `bridge/inbox/` or `bridge/outbox/`, follow the
+working tree safety protocol **before touching anything**:
+
+Full protocol: `.ai-assistance/conventions/code-working-tree-protocol.md`
+
+Summary:
+1. Check for `.ai-assistance/bridge/LOCK` — stop and inform user if actively locked
+2. Acquire lock (watermark: agent, user, timestamp, expiry, intent, files)
+3. Check for unstaged changes that overlap with your planned files — if overlap, commit them first as `wip: <description>`; if no overlap, proceed without touching them
+4. Apply your changes
+5. Commit with a descriptive message
+6. Release lock (`rm .ai-assistance/bridge/LOCK`)
+
+---
+
+## Bridge: CoWork ↔ Claude Code
+
+A file-based channel for delegating tasks between CoWork and Code.
+Full protocol: `.ai-assistance/bridge/CLAUDE.md`
+
+### On every Code session startup
+
+**Before responding to the user, read the bridge status file:**
+
+```bash
+cat .ai-assistance/bridge/STATUS 2>/dev/null || echo "no status yet"
+```
+
+The `SessionStart` hook runs `bridge-init.sh` automatically and writes its output to
+`bridge/STATUS`. Reading this file tells you immediately whether there are pending tasks.
+
+If `pending > 0`: tell the user "I have N pending bridge task(s): [list]" and ask whether
+to process them now before starting other work.
+
+If the STATUS file is missing (first session or hook didn't run): run manually:
+```bash
+bash .ai-assistance/scripts/bridge-init.sh
+```
+
+### Why Code doesn't report pending tasks automatically on startup
+
+Claude Code is passive — it waits for a user prompt before doing anything, regardless
+of what hooks run or what this file says. The `SessionStart` hook runs `bridge-init.sh`
+and writes `bridge/STATUS`, but Code will not speak unprompted.
+
+**The intended workflow:** at the start of each session, ask:
+> "Any pending tasks?"
+
+Code will read `bridge/STATUS` (already written by the hook) and report immediately.
+This is one short question — the right tradeoff for an interactive tool.
+
+Hook stdout is also not injected into Code's context — only the STATUS file is readable.
+Do not attempt to use hook output as a message source; write to a file instead.
+
+### Before writing a bridge task
+
+Check `.ai-assistance/capabilities/[your-env].md` — only bridge what you genuinely cannot do yourself.
+
+### Key paths
+
+| Path | Purpose |
+|------|---------|
+| `.ai-assistance/bridge/inbox/` | Tasks waiting to be processed |
+| `.ai-assistance/bridge/outbox/` | Completed results |
+| `.ai-assistance/bridge/archive/` | Completed pairs (audit trail) |
+| `.ai-assistance/bridge/STATUS` | Bridge status file written by bridge-init.sh on session start |
+| `.ai-assistance/bridge/LOCK` | Working tree lock file (never commit; gitignored) |
+| `.ai-assistance/capabilities/` | Per-environment capability registry |
+| `.ai-assistance/capabilities/assumptions-log.md` | Dated assumptions + verification status |
+| `.ai-assistance/conventions/` | Instruction file structure rules |
+| `.ai-assistance/scripts/` | Token-offload scripts (see `scripts/CLAUDE.md`) |

data/Gemfile

@@ -1,6 +1,30 @@
-source "https://rubygems.org"
-
-git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
-
-# Specify your gem's dependencies in ecoportal-api.gemspec
-gemspec
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in ecoportal-api.gemspec
+gemspec
+
+# Pin graphlient to our fork's FROZEN release branch `pre-v0.0.9` (a snapshot of the fork's
+# master, which carries the DSL/directive work — #115 to_query_string/spread, #116 directives
+# DSL / on(:Type) / fragment(:Name); lib/ is byte-identical to feature/directives-dsl-support).
+# Frozen so the gem (and downstream repos) pin a stable ref, not a moving feature branch.
+# Revisit when the fork cuts a real gem release (>= 0.8.x with these features published).
+# Frozen: 2026-07-02.
+gem 'graphlient', git:    'https://github.com/rellampec/graphlient.git',
+                  branch: 'pre-v0.0.9'
+
+# NOTE: no graphql-client override. It is a TRANSITIVE dependency of graphlient and
+# resolves to the published 0.26.0 — this gem does not use graphql-client directly
+# (queries go through the graphlient DSL; the Group-3 refactor removed `client.parse`),
+# so the fork's revival MRs (#79–#82, still unattended upstream) are not required here.
+# FUTURE: we plan to retake the graphql-client fork revival and land more graphlient +
+# ecoportal-api-graphql features (and downstream) — re-introduce a pin at that point.
+# See memory: project-fork-revival-strategy / project-graphql-client-redesign.
+
+# Optional — only needed for SearchConf::AIGenerator live tests.
+# Not added to gemspec; callers must install it themselves.
+# Uses http source to bypass local SSL inspection (e.g. Norton Antivirus).
+source 'http://rubygems.org' do
+  gem 'anthropic'
+end

data/Rakefile

@@ -1,38 +1,90 @@
-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
+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 'Generate JSON dependency/structure map -> .ai-assistance/code/dep-graph.json'
+task :dep_graph do
+  load '.ai-assistance/scripts/dep_graph.rb'
+  output = '.ai-assistance/code/dep-graph.json'
+  DepGraph.run(lib_dir: 'lib', output_path: output)
+  puts "Written -> #{output}"
+end
+
+desc 'Detect workflow-space schema drift: COMMAND_MAP vs stored introspection + SCHEMA_VERSION currency'
+task :schema_drift do
+  require 'json'
+
+  schema_glob  = '.ai-assistance/tmp/*_live_ep_graphql_schema.graphql.json'
+  schema_files = Dir[schema_glob]
+  abort "No schema file at #{schema_glob} — re-run introspection first" if schema_files.empty?
+
+  schema_path = schema_files.last
+  puts "Schema: #{schema_path}"
+  schema_date = File.basename(schema_path)[/\d{8}/]
+
+  schema = JSON.parse(File.read(schema_path))
+  types  = schema.dig('data', '__schema', 'types').to_h { |t| [t['name'], t] }
+  wci    = types['WorkflowCommandInput'] or abort('WorkflowCommandInput not found in schema')
+
+  schema_keys = Set.new(wci['inputFields'].map { |f| f['name'] })
+
+  cmd_src  = File.read('lib/ecoportal/api/graphql/input/workflow_command.rb')
+  gem_keys = Set.new(cmd_src.scan(/^\s+(\w+):\s+'Ecoportal/).flatten)
+
+  added   = (schema_keys - gem_keys).sort
+  removed = (gem_keys - schema_keys).sort
+
+  puts "\n=== WorkflowCommandInput (#{schema_keys.size} schema / #{gem_keys.size} gem) ==="
+  if added.empty? && removed.empty?
+    puts "In sync — no drift"
+  else
+    added.each   { |k| puts "  + #{k}  (in schema, missing from COMMAND_MAP)" }
+    removed.each { |k| puts "  - #{k}  (in COMMAND_MAP, absent from schema)" }
+  end
+
+  puts "\n=== SCHEMA_VERSION constants (expected #{schema_date}) ==="
+  mismatches = []
+  Dir['lib/**/*.rb'].each do |f|
+    File.read(f).scan(/SCHEMA_VERSION\s*=\s*'(\d+)'\.freeze/).each do |m|
+      mismatches << "  #{f}: '#{m[0]}'" if m[0] != schema_date
+    end
+  end
+  mismatches.empty? ? puts("All match #{schema_date}") : mismatches.each { |m| puts m }
+
+  abort "\nDrift detected — update gem files before bumping schema date" unless added.empty? && removed.empty?
+end
+
+desc 'default task: runs rubocop and rspec'
+task :default do
+  Rake::Task[:rubocop].invoke
+ensure
+  Rake::Task[:spec].invoke
+end