ecoportal-api-graphql 1.3.5 → 1.3.9

data/.ai-assistance/skills/gemini-assist/gemini_ask.rb

@@ -0,0 +1,240 @@
+#!/usr/bin/env ruby
+#
+# Gemini Assist — packs files + prompt and queries the Gemini API.
+#
+# Usage:
+#   ruby .ai-assistance/skills/gemini-assist/gemini_ask.rb \
+#     --prompt "Your question here" \
+#     --files lib/foo.rb lib/bar.rb
+#
+#   ruby .ai-assistance/skills/gemini-assist/gemini_ask.rb \
+#     --prompt-file .ai-assistance/skills/gemini-assist/prompts/review.txt \
+#     --files "lib/**/*.rb"
+#
+# Requires:  GEMINI_API_KEY environment variable (or set in .env)
+# Optional:  GEMINI_MODEL   environment variable (default: gemini-1.5-pro)
+
+require "json"
+require "net/http"
+require "openssl"
+require "optparse"
+require "rbconfig"
+require "uri"
+
+# Returns an SSL certificate store that works cross-platform.
+# Priority: SSL_CERT_FILE env var → RubyInstaller bundled cacert.pem →
+# OpenSSL compiled-in default → system paths.
+# VERIFY_PEER is always on — verification is never disabled.
+def ssl_cert_store
+  store = OpenSSL::X509::Store.new
+
+  candidates = [
+    ENV["FALLBACK_SSL_CERT_FILE"],
+    ENV["SSL_CERT_FILE"],
+    File.join(RbConfig::CONFIG["prefix"], "ssl", "cacert.pem"),
+    OpenSSL::X509::DEFAULT_CERT_FILE
+  ].compact
+
+  cert_file = candidates.find { |f| File.file?(f) }
+
+  if cert_file
+    store.add_file(cert_file)
+  else
+    store.set_default_paths
+  end
+
+  store
+end
+
+DEFAULT_MODEL = "gemini-2.5-pro"
+API_BASE      = "https://generativelanguage.googleapis.com/v1beta/models"
+
+SYSTEM_PREAMBLE = <<~PREAMBLE.strip
+  You are an expert Ruby developer reviewing code for the ecoportal-api-graphql gem.
+  This gem provides a GraphQL client layer. It uses graphql-ruby, graphlient, and graphql-client upstream,
+  and is consumed by eco-helpers downstream. Backwards compatibility matters.
+
+  When you identify issues, be specific: include file name, approximate line reference, and a concrete suggestion.
+  Flag hallucination risk: if you're unsure about something, say so rather than guessing.
+PREAMBLE
+
+# Loads key=value pairs from a .env file into ENV (skips already-set keys).
+def load_dotenv(path = ".env")
+  return unless File.file?(path)
+
+  File.foreach(path) do |raw|
+    line = raw.strip
+    next if line.empty? || line.start_with?("#") || !line.include?("=")
+
+    key, value = line.split("=", 2)
+    key   = key.strip
+    value = value.to_s.strip
+      .delete_prefix('"').delete_suffix('"')
+      .delete_prefix("'").delete_suffix("'")
+    ENV[key] ||= value if key
+  end
+end
+
+# Expands glob patterns and returns formatted file blocks.
+def load_files(patterns)
+  patterns.flat_map do |pattern|
+    paths = Dir.glob(pattern, File::FNM_DOTMATCH).select { |p| File.file?(p) }.sort
+    paths = [pattern] if paths.empty?
+
+    paths.filter_map do |path|
+      unless File.file?(path)
+        warn "[warn] skipping non-file: #{path}"
+        next
+      end
+
+      text = File.read(path, encoding: "utf-8:utf-8", invalid: :replace, undef: :replace)
+      "### FILE: #{path}\n```ruby\n#{text}\n```"
+    rescue => e
+      warn "[warn] could not read #{path}: #{e.message}"
+      nil
+    end
+  end
+end
+
+def build_prompt(user_prompt, file_contents)
+  parts = [SYSTEM_PREAMBLE, ""]
+
+  if file_contents.any?
+    parts << "## Files provided for context\n"
+    parts.concat(file_contents)
+    parts << ""
+  end
+
+  parts << "## Task\n"
+  parts << user_prompt.strip
+  parts.join("\n")
+end
+
+
+def list_models(api_key)
+  url  = URI("#{API_BASE.sub('/models', '')}/models?key=#{api_key}&pageSize=50")
+  http = Net::HTTP.new(url.host, url.port)
+  http.use_ssl     = true
+  http.cert_store  = ssl_cert_store
+  http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+
+  response = http.get(url)
+  abort "[error] HTTP #{response.code}: #{response.body}" unless response.is_a?(Net::HTTPSuccess)
+
+  models = JSON.parse(response.body).fetch("models", [])
+  models
+    .select { |m| m["name"]&.include?("gemini") }
+    .sort_by { |m| m["name"] }
+    .each do |m|
+      methods = Array(m["supportedGenerationMethods"]).join(", ")
+      puts "  #{m['name'].sub('models/', '').ljust(40)} #{m.fetch('displayName', '')} [#{methods}]"
+    end
+end
+
+def call_gemini(prompt, model:, api_key:)
+  url = URI("#{API_BASE}/#{model}:generateContent?key=#{api_key}")
+
+  payload = {
+    contents:         [{ parts: [{ text: prompt }] }],
+    generationConfig: {
+      temperature:     0.2,
+      maxOutputTokens: 8192
+    }
+  }
+
+  http               = Net::HTTP.new(url.host, url.port)
+  http.use_ssl       = true
+  http.cert_store    = ssl_cert_store
+  http.verify_mode   = OpenSSL::SSL::VERIFY_PEER
+  http.read_timeout  = 120
+  http.write_timeout = 120
+
+  request = Net::HTTP::Post.new(url)
+  request["Content-Type"] = "application/json"
+  request.body = payload.to_json
+
+  response = http.request(request)
+
+  unless response.is_a?(Net::HTTPSuccess)
+    abort "[error] HTTP #{response.code}: #{response.body}"
+  end
+
+  result = JSON.parse(response.body)
+  result.dig("candidates", 0, "content", "parts", 0, "text") or
+    abort "[error] unexpected response shape:\n#{JSON.pretty_generate(result)}"
+rescue JSON::ParserError => e
+  abort "[error] could not parse Gemini response: #{e.message}"
+end
+
+def parse_options
+  options = { files: [], model: nil, output: nil }
+
+  parser = OptionParser.new do |opts|
+    opts.banner = "Usage: gemini_ask.rb --prompt TEXT [--files GLOB...] [options]"
+
+    opts.on("--prompt TEXT",      "Prompt text inline")           { |v| options[:prompt]      = v }
+    opts.on("--prompt-file PATH", "Path to a file with prompt")   { |v| options[:prompt_file] = v }
+    opts.on("--files GLOBS",      "Files or glob patterns (repeatable)") { |v| options[:files] << v }
+    opts.on("--model MODEL",      "Gemini model override")        { |v| options[:model]       = v }
+    opts.on("--output PATH",      "Write response to file")       { |v| options[:output]      = v }
+    opts.on("--list-models",      "List available Gemini models") { |_| options[:list_models] = true }
+    opts.on("-h", "--help",       "Show this help")               { puts opts; exit }
+  end
+
+  parser.parse!
+  options
+end
+
+def resolve_prompt(options)
+  if options[:prompt]
+    options[:prompt]
+  elsif options[:prompt_file]
+    File.read(options[:prompt_file], encoding: "utf-8")
+  else
+    abort "[error] must supply --prompt or --prompt-file"
+  end
+end
+
+#--
+# Entry point
+#++
+load_dotenv
+
+options = parse_options
+
+if options[:list_models]
+  load_dotenv
+  api_key = ENV.fetch("GEMINI_API_KEY") { abort "[error] GEMINI_API_KEY not set" }
+  puts "\nAvailable Gemini models:\n"
+  list_models(api_key)
+  exit
+end
+
+api_key = ENV.fetch("GEMINI_API_KEY") { abort "[error] GEMINI_API_KEY is not set (check .env)" }
+model   = options[:model] || ENV.fetch("GEMINI_MODEL", DEFAULT_MODEL)
+
+user_prompt   = resolve_prompt(options)
+file_contents = load_files(options[:files])
+
+warn "[info] Loaded #{file_contents.size} file(s) into context." if file_contents.any?
+
+full_prompt = build_prompt(user_prompt, file_contents)
+est_tokens  = full_prompt.length / 4
+warn "[info] Model: #{model} | Estimated input tokens: ~#{est_tokens.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\1,').reverse}"
+warn "[info] Querying Gemini..."
+
+response_text = call_gemini(full_prompt, model: model, api_key: api_key)
+
+if options[:output]
+  File.write(options[:output], response_text, encoding: "utf-8")
+  warn "[info] Response written to #{options[:output]}"
+else
+  puts
+  puts "=" * 60
+  puts "GEMINI RESPONSE"
+  puts "=" * 60
+  puts response_text
+  puts "=" * 60
+  puts
+  puts "[reminder] Always verify Gemini's claims against actual code before acting on them."
+end

data/.ai-assistance/skills/gemini-assist/prompts/cycle_end_review.txt

@@ -0,0 +1,25 @@
+You are doing a cycle-end code review for the ecoportal-api-graphql Ruby gem.
+
+Review the provided files for:
+1. Correctness — logic errors, edge cases not handled, incorrect assumptions.
+2. Backwards compatibility — anything that could break eco-helpers (the downstream consumer).
+3. Consistency — does the code follow the patterns established elsewhere in this gem?
+4. Completeness — are there obvious gaps (missing specs, missing error handling, etc.)?
+
+Respond in this format:
+
+## Summary
+One paragraph: overall assessment.
+
+## Issues Found
+For each issue:
+- **Severity:** [critical | major | minor]
+- **File:** `path/to/file.rb`
+- **Concern:** What the problem is.
+- **Suggestion:** What to do about it.
+
+## No Issues Found In
+List areas that look good.
+
+## Uncertain / Needs Human Verification
+Anything you're not confident about — flag it here rather than guessing.

data/.ai-assistance/skills/graphql-schema-analysis/SKILL.md

@@ -0,0 +1,261 @@
+# SKILL: GraphQL Schema Analysis
+
+**Purpose:** Systematically analyse a GraphQL schema (introspection JSON) to understand
+type coverage, identify mutation/query patterns, compare against a Ruby gem implementation,
+and produce structured documentation for AI agents.
+
+**When to use:** Before implementing new gem coverage for any GraphQL API area, or when
+auditing existing coverage against a live schema.
+
+---
+
+## Prerequisites
+
+1. An introspection JSON file from the live API — standard `__schema` introspection format.
+   - Fetch it from a live or staging instance.
+   - Store it in `.ai-assistance/tmp/` (git-ignored).
+   - File naming convention: `YYYYMMDDTHHMMSS_<env>_graphql_schema.json`
+
+2. The existing gem code for context (read `lib/` and `.ai-assistance/code/`).
+
+---
+
+## Step 1 — Orientate on Scale
+
+Before diving in, understand the size:
+
+```bash
+# File size
+(Get-Item schema.json).Length / 1KB   # PowerShell
+wc -c schema.json                     # Unix
+
+# Count types and mutations
+ruby -rjson -e '
+  s = JSON.parse(File.read("schema.json")).dig("data","__schema")
+  types = s["types"].reject { |t| t["name"].start_with?("__") }
+  puts "Types:     #{types.count}"
+  puts "Objects:   #{types.count { |t| t["kind"] == "OBJECT" }}"
+  puts "Inputs:    #{types.count { |t| t["kind"] == "INPUT_OBJECT" }}"
+  puts "Enums:     #{types.count { |t| t["kind"] == "ENUM" }}"
+  puts "Unions:    #{types.count { |t| t["kind"] == "UNION" }}"
+  puts "Interfaces:#{types.count { |t| t["kind"] == "INTERFACE" }}"
+  mut = types.find { |t| t["name"] == "Mutation" }
+  puts "Mutations: #{mut ? mut["fields"].count : 0}"
+  q = types.find { |t| t["name"] == "Query" }
+  puts "Queries:   #{q ? q["fields"].count : 0}"
+'
+```
+
+---
+
+## Step 2 — Map Top-Level Structure
+
+Extract the root Query and Mutation fields. These are the entry points for all API calls:
+
+```ruby
+ruby -rjson -e '
+  s = JSON.parse(File.read("schema.json")).dig("data","__schema","types")
+  type_map = s.each_with_object({}) { |t, h| h[t["name"]] = t }
+
+  def type_str(t)
+    return "?" unless t
+    case t["kind"]
+    when "NON_NULL" then "#{type_str(t["ofType"])}!"
+    when "LIST"     then "[#{type_str(t["ofType"])}]"
+    else t["name"]
+    end
+  end
+
+  puts "=== QUERY ==="
+  type_map["Query"]["fields"].each { |f| puts "  #{f["name"]}: #{type_str(f["type"])}" }
+
+  puts "\n=== MUTATIONS ==="
+  type_map["Mutation"]["fields"].each { |f| puts "  #{f["name"]}" }
+'
+```
+
+**Key questions to answer:**
+- Is there a primary gateway object? (e.g. `currentOrganization`) Under which everything nests?
+- Which areas have the most mutations? (Group by prefix: `create*/update*/destroy*`)
+- Are mutations consistent? (All use `input: SomeType!` or mixed styles?)
+
+---
+
+## Step 3 — Identify Core Patterns
+
+Look for schema-wide patterns before diving into individual types. These inform how the
+Ruby gem should be designed:
+
+```ruby
+ruby -rjson -e '
+  s = JSON.parse(File.read("schema.json")).dig("data","__schema","types")
+  type_map = s.each_with_object({}) { |t, h| h[t["name"]] = t }
+
+  # Check mutation argument patterns
+  muts = type_map["Mutation"]["fields"]
+  single_input = muts.count { |f| f["args"].length == 1 && f["args"][0]["name"] == "input" }
+  puts "Mutations with single input: #{single_input}/#{muts.count}"
+
+  # Find shared patterns
+  puts "\nTypes containing patchVer:"
+  s.select { |t| (t["fields"] || []).any? { |f| f["name"] == "patchVer" } }.each { |t| puts "  #{t["name"]}" }
+
+  puts "\nInput types using IdDiffInput:"
+  s.select { |t| t["kind"] == "INPUT_OBJECT" }.each do |t|
+    t["inputFields"].each do |f|
+      next unless ["name","ofType"].all? { |k| f["type"].to_s.include?("IdDiff") } ||
+                  f["type"]["name"] == "IdDiffInput" ||
+                  (f["type"]["ofType"] || {})["name"] == "IdDiffInput"
+      puts "  #{t["name"]}.#{f["name"]}"
+    end
+  end
+'
+```
+
+**Patterns to look for:**
+- **Concurrency control:** Any type with `patchVer` (optimistic locking — must query before update)
+- **Delta sync:** `*Delta` query fields returning `[DeltaResult]` — incremental sync support
+- **IdDiff pattern:** `IdDiffInput { additions, removals }` for array relationship updates
+- **OneToMany inputs:** `*OneToManyInput { additions, updates, deletions }` for complex nested updates
+- **Payload pattern:** Do mutations return `{ item, errors }` or `{ payload, errors }` or other?
+- **Connection pattern:** Paginated lists use Relay-style `*Connection { edges { node }, pageInfo }`
+
+---
+
+## Step 4 — Extract a Specific Type
+
+For each area you're implementing, extract the full type definition:
+
+```ruby
+ruby -rjson -e '
+  s = JSON.parse(File.read("schema.json")).dig("data","__schema","types")
+  type_map = s.each_with_object({}) { |t, h| h[t["name"]] = t }
+
+  def type_str(t); return "?" unless t; case t["kind"]; when "NON_NULL" then "#{type_str(t["ofType"])}!"; when "LIST" then "[#{type_str(t["ofType"])}]"; else t["name"]; end; end
+
+  def print_type(type_map, name)
+    t = type_map[name]; return puts "NOT FOUND: #{name}" unless t
+    puts "\n=== #{name} (#{t["kind"]}) ==="
+    if t["kind"] == "ENUM"
+      (t["enumValues"] || []).each { |v| puts "  #{v["name"]}" }
+      return
+    end
+    (t["fields"] || t["inputFields"] || []).each do |f|
+      args = (f["args"] || []).map { |a| "#{a["name"]}: #{type_str(a["type"])}" }
+      arg_str = args.empty? ? "" : "(#{args.join(", ")})"
+      puts "  #{f["name"]}#{arg_str}: #{type_str(f["type"])}"
+    end
+  end
+
+  # Replace with the type names you need:
+  %w[ TypeNameHere InputTypeHere ].each { |n| print_type(type_map, n) }
+'
+```
+
+**For each area, extract:**
+1. The output type(s) — what the query/mutation returns
+2. The input type(s) — what the mutation accepts
+3. The mutation args — confirm `input: InputType!` single-wrapper vs separate args
+4. Related enums — field options, state values
+
+---
+
+## Step 5 — Compare Against Gem Implementation
+
+For each implemented area, systematically check coverage:
+
+```
+Schema field          | Ruby gem mapping              | Status
+----------------------|-------------------------------|--------
+id: ID!               | passkey :id                   | ✓
+name: String!         | passthrough :name             | ✓
+patchVer: Int!        | passthrough :patchVer         | ✓ (queried)
+                      | (not in mutation input yet)   | ✗ (not injected)
+recurrence: Recurrence| —                             | ✗ MISSING
+```
+
+**Gem mapping patterns (ecoportal-api-graphql):**
+- `passkey :fieldName` — ID primary key
+- `passthrough :fieldName` — scalar, string, enum
+- `passboolean :fieldName` — boolean field
+- `passdate :fieldName` — DateTime (read-only dates)
+- `passarray :fieldName` — array of scalars
+- `embeds_one :fieldName, klass: SomeClass` — nested object
+- `embeds_many :fieldName, klass: SomeClass` — array of objects
+- `read_only!` modifier — field cannot be written
+- `root!` on class — excluded from diff (lookup/reference, not owned)
+
+---
+
+## Step 6 — Document Findings
+
+Write to `.ai-assistance/code/<area>.md` covering:
+1. Schema type inventory (output types, input types, enums)
+2. Mutation/query signatures
+3. Coverage gap table
+4. Key patterns and invariants (patchVer, IdDiff, etc.)
+5. Decisions made (deferred features, simplifications)
+
+Reference: see `.ai-assistance/code/schema_analysis.md` and `diff_as_input.md` for examples.
+
+---
+
+## Key Extraction Scripts (Quick Reference)
+
+```ruby
+# Find all types mentioning a keyword
+type_map.keys.select { |k| k.match?(/keyword/i) }.sort
+
+# Find all mutations for an area
+type_map["Mutation"]["fields"].select { |f| f["name"].match?(/area/i) }.map { |f| f["name"] }
+
+# Find which types have a specific field
+type_map.values.select { |t| (t["fields"] || []).any? { |f| f["name"] == "fieldName" } }.map { |t| t["name"] }
+
+# Get all enums with their values
+type_map.values.select { |t| t["kind"] == "ENUM" }.each do |t|
+  puts "#{t["name"]}: #{t["enumValues"].map { |v| v["name"] }.join(" | ")}"
+end
+
+# Check mutation argument pattern for one mutation
+mut = type_map["Mutation"]["fields"].find { |f| f["name"] == "mutationName" }
+puts mut["args"].map { |a| "#{a["name"]}: #{type_str(a["type"])}" }
+```
+
+---
+
+## Common Gotchas
+
+1. **Schema vs source code divergence.** The introspection JSON is from the live API.
+   Source code may be a different version. Always trust the introspection JSON.
+
+2. **Non-null vs nullable.** `field: Type!` means non-null; `field: Type` is nullable.
+   For mutations, non-null input fields are required. Always check nullability before
+   setting `required: true` in a Ruby input class.
+
+3. **Input type vs output type names.** `UpdateActionInput` ≠ `Action`. Always check
+   the specific input type, not the output type, when building mutation inputs.
+
+4. **Relay Connection types.** `FooConnection { edges { node: Foo }, pageInfo }` —
+   the actual data is under `edges.node` or (with the `nodes` shortcut) directly `nodes`.
+
+5. **Union types.** `PageUnion = BasicPage | PhasedPage` — always include `__typename`
+   in queries on union types so you can dispatch to the right Ruby class.
+
+6. **`patchVer` = must read before write.** Any type with `patchVer` in the schema
+   requires you to fetch the current value before updating. You cannot construct a
+   valid update input without it.
+
+7. **`IdDiffInput` in Update vs `[ID!]` in Create.** Create mutations often take flat
+   ID arrays; update mutations use `IdDiffInput`. Build separate Create and Update
+   input classes rather than sharing one.
+
+---
+
+## Output: What to Write
+
+After analysis, produce:
+- `.ai-assistance/code/<area>.md` — technical spec for the area
+- `.ai-assistance/projects/<area>/TODO.md` — phased implementation plan
+- `.ai-assistance/projects/<area>/DECISIONS.md` — rationale for scope choices
+- Update `.ai-assistance/code/schema_analysis.md` coverage table with findings