ecoportal-api-graphql 1.3.5 → 1.3.9

data/scripts/auto-worker-scheduler.sh

@@ -0,0 +1,386 @@
+#!/usr/bin/env bash
+# auto-worker-scheduler.sh
+# Scheduler for auto-todo-worker. Called by the Claude Code Stop hook.
+# Reads local config, checks token budget and conflict guard, then
+# launches the worker as a background process if all gates pass.
+#
+# Log format: TIMESTAMP | ACTION | REASON
+# Log file:   .ai-assistance/local/auto-worker-changes.log
+#
+# Usage: bash scripts/auto-worker-scheduler.sh
+#        (called automatically by Stop hook — no arguments)
+#
+# Requires: jq (for JSON parsing). Falls back to grep/sed on missing jq.
+
+set -euo pipefail
+
+# ---------------------------------------------------------------------------
+# Paths (all relative — script must be run from repo root)
+# ---------------------------------------------------------------------------
+TOKEN_BUDGET_JSON=".ai-assistance/token-budget.json"
+LAST_RUN_JSON=".ai-assistance/local/auto-worker-last-run.json"
+SESSION_LOCK=".ai-assistance/local/session.lock"
+CHANGES_LOG=".ai-assistance/local/auto-worker-changes.log"
+STDOUT_LOG=".ai-assistance/local/auto-worker-stdout.log"
+STDERR_LOG=".ai-assistance/local/auto-worker-stderr.log"
+PROMPT_FILE=".ai-assistance/local/auto-worker-prompt.txt"
+
+# --dry-run: run every gate and log what WOULD launch, but spawn nothing.
+# Use this to smoke-test the gates without burning tokens on a real worker.
+DRY_RUN=0
+if [ "${1:-}" = "--dry-run" ]; then
+  DRY_RUN=1
+fi
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+# ai_log_usage <component> <action> <detail> [session_id]
+# Inline copy — scheduler is self-contained; common.sh is not sourced here.
+# Never fails fatally; all errors suppressed.
+ai_log_usage() {
+  local component="${1:-unknown}"
+  local action="${2:-run}"
+  local detail="${3:-}"
+  local session_id="${4:-}"
+  local log_dir=".ai-assistance/local/kpi"
+  local week
+  week=$(date +%Y-W%V 2>/dev/null || echo "unknown")
+  local log_file="${log_dir}/usage-${week}.jsonl"
+  local ts
+  ts=$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || echo "unknown")
+  mkdir -p "$log_dir" 2>/dev/null || true
+  printf '{"component":"%s","action":"%s","detail":"%s","ts":"%s","session_id":"%s"}\n' \
+    "$component" "$action" "$detail" "$ts" "$session_id" >> "$log_file" 2>/dev/null || true
+}
+
+log_action() {
+  local action="$1"
+  local reason="$2"
+  local ts
+  ts=$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || date +"%Y-%m-%dT%H:%M:%SZ")
+  mkdir -p "$(dirname "$CHANGES_LOG")"
+  printf "%s | %s | %s\n" "$ts" "$action" "$reason" >> "$CHANGES_LOG"
+}
+
+# Read a JSON field using jq if available, otherwise grep+sed fallback.
+# Usage: json_field <file> <dotted.key>   e.g. json_field config.json auto_worker.enabled
+json_field() {
+  local file="$1"
+  local key="$2"
+  if command -v jq >/dev/null 2>&1; then
+    jq -r ".${key} // empty" "$file" 2>/dev/null
+  else
+    # Minimal fallback: grep for the last segment key, extract bare value.
+    local leaf
+    leaf=$(printf '%s' "$key" | sed 's/.*\.//')
+    grep -o "\"${leaf}\"[[:space:]]*:[[:space:]]*[^,}]*" "$file" 2>/dev/null \
+      | tail -1 \
+      | sed 's/.*:[[:space:]]*//' \
+      | tr -d '"' \
+      | tr -d ' '
+  fi
+}
+
+# Make silent failures visible. With `set -e`, any unexpected non-zero exit
+# fires this trap and records an ERROR line before the script dies. The Stop
+# hook swallows stderr (`2>/dev/null || true`), so without this an early
+# failure (missing jq/python, malformed JSON, etc.) would leave no trace at
+# all — which is exactly how this script went dark without anyone noticing.
+trap 'rc=$?; log_action "ERROR" "scheduler aborted at line ${LINENO} (rc=${rc})"' ERR
+
+# ---------------------------------------------------------------------------
+# Gate 1: auto_worker.enabled
+# ---------------------------------------------------------------------------
+
+if [ ! -f "$TOKEN_BUDGET_JSON" ]; then
+  log_action "SKIP" "token-budget.json not found — auto_worker not configured"
+  ai_log_usage "script/auto-worker-scheduler" "skip" "auto_worker not enabled -- token-budget.json not found"
+  exit 0
+fi
+
+enabled=$(json_field "$TOKEN_BUDGET_JSON" "auto_worker.enabled")
+if [ "$enabled" != "true" ]; then
+  log_action "SKIP" "auto_worker.enabled is false or absent in token-budget.json"
+  ai_log_usage "script/auto-worker-scheduler" "skip" "auto_worker not enabled"
+  exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Gate 1b: Eligible work must exist — at least one [auto] / [auto:last] item
+# ---------------------------------------------------------------------------
+# Without this gate, every trigger spins up a full `claude --print` worker even
+# when TODO.md has zero tagged items — the worker then no-ops, burning a launch
+# (and tokens) for nothing. This was the pattern behind the 42 historical
+# launches that completed no work, and it is also why a repo with no TODO.md at
+# all (e.g. a fresh sibling) must SKIP rather than launch into an error.
+# The tag set is the eligibility boundary defined in
+# standards/tooling/auto-worker-eligibility.md.
+# NOTE: \[auto\] does NOT match [auto:last] — the regex MUST be \[auto(:last)?\].
+TODO_FILE="TODO.md"
+if [ ! -f "$TODO_FILE" ]; then
+  log_action "SKIP" "No TODO.md in repo root — no eligible work to schedule"
+  ai_log_usage "script/auto-worker-scheduler" "skip" "no TODO.md present"
+  exit 0
+fi
+if ! grep -qE '\[auto(:last)?\]' "$TODO_FILE"; then
+  log_action "SKIP" "No eligible work — no [auto] or [auto:last] items in TODO.md"
+  ai_log_usage "script/auto-worker-scheduler" "skip" "no [auto]/[auto:last] items in TODO.md"
+  exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Gate 2: Conflict guard — check for active Claude session via session.lock
+# ---------------------------------------------------------------------------
+
+if [ -f "$SESSION_LOCK" ]; then
+  lock_content=""
+  if [ -r "$SESSION_LOCK" ]; then
+    lock_content=$(cat "$SESSION_LOCK" 2>/dev/null || true)
+  fi
+  log_action "SKIP" "Active Claude session detected (session.lock present: ${lock_content})"
+  ai_log_usage "script/auto-worker-scheduler" "skip" "session.lock present"
+  exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Gate 3: Token budget threshold check
+# ---------------------------------------------------------------------------
+# Find the current ISO week KPI file. Format: weekly-YYYY-WNN.json
+# We compute ISO week ourselves for portability.
+
+iso_week() {
+  # Returns YYYY-WNN string for today (ISO 8601 week numbering)
+  if command -v python3 >/dev/null 2>&1; then
+    python3 -c "
+import datetime
+today = datetime.date.today()
+iso = today.isocalendar()
+print('%04d-W%02d' % (iso[0], iso[1]))
+"
+  elif command -v python >/dev/null 2>&1; then
+    python -c "
+import datetime
+today = datetime.date.today()
+iso = today.isocalendar()
+print('%04d-W%02d' % (iso[0], iso[1]))
+"
+  else
+    # Fallback: use date command Week-of-year (not strictly ISO but close enough)
+    date +"%Y-W%V" 2>/dev/null || date +"%Y-W%U"
+  fi
+}
+
+KPI_DIR=".ai-assistance/local/kpi"
+WEEK_KEY=$(iso_week)
+KPI_FILE="${KPI_DIR}/weekly-${WEEK_KEY}.json"
+
+# Read quota and usage from KPI file (if present)
+weekly_tokens_used=0
+weekly_quota=0
+window_start_ts=""   # ISO timestamp of first session start in current 5-hour window
+
+if [ -f "$KPI_FILE" ] && command -v jq >/dev/null 2>&1; then
+  # Sum tokens_used across all sessions
+  weekly_tokens_used=$(jq '[.sessions[]?.tokens_used // 0] | add // 0' "$KPI_FILE" 2>/dev/null || echo "0")
+  weekly_quota=$(jq -r '.quota // 0' "$KPI_FILE" 2>/dev/null || echo "0")
+
+  # Find most recent session start to compute reset window
+  window_start_ts=$(jq -r '
+    [.sessions[]?.session_start // empty] | sort | last // empty
+  ' "$KPI_FILE" 2>/dev/null || true)
+fi
+
+# Read quota from token-budget.json as fallback
+if [ "$weekly_quota" = "0" ] || [ -z "$weekly_quota" ]; then
+  quota_from_config=$(json_field "$TOKEN_BUDGET_JSON" "weekly_quota.total_tokens")
+  if [ "$quota_from_config" != "null" ] && [ -n "$quota_from_config" ]; then
+    weekly_quota="$quota_from_config"
+  fi
+fi
+
+# If no quota is set (null), skip the threshold gate entirely
+if [ "$weekly_quota" = "0" ] || [ "$weekly_quota" = "null" ] || [ -z "$weekly_quota" ]; then
+  log_action "OK" "No weekly quota set — skipping token threshold gate"
+else
+  # Calculate usage percentage
+  if command -v python3 >/dev/null 2>&1; then
+    usage_pct=$(python3 -c "
+used = float('${weekly_tokens_used}' or '0')
+quota = float('${weekly_quota}')
+print('%.1f' % (used / quota * 100) if quota > 0 else '0')
+")
+  else
+    usage_pct=0
+  fi
+
+  # Determine time remaining in current 5-hour reset window
+  # 5-hour window = 18000 seconds
+  window_seconds_elapsed=0
+  if [ -n "$window_start_ts" ] && command -v python3 >/dev/null 2>&1; then
+    window_seconds_elapsed=$(python3 -c "
+import datetime, sys
+try:
+    ts = '${window_start_ts}'.replace('Z', '+00:00')
+    start = datetime.datetime.fromisoformat(ts)
+    now = datetime.datetime.now(datetime.timezone.utc)
+    elapsed = (now - start).total_seconds()
+    print(int(max(0, elapsed)))
+except Exception:
+    print(0)
+")
+  fi
+
+  WINDOW_DURATION=18000   # 5 hours in seconds
+  window_remaining=$(( WINDOW_DURATION - window_seconds_elapsed ))
+  if [ "$window_remaining" -lt 0 ]; then
+    window_remaining=0
+  fi
+  window_remaining_min=$(( window_remaining / 60 ))
+
+  # Determine threshold based on time remaining in window (ADR-007 table)
+  # >120 min -> 65%; 60-120 -> 75%; 45-60 -> 80%; 30-45 -> 90%; 15-30 -> 95%; <15 -> skip
+  if [ "$window_remaining_min" -lt 15 ]; then
+    log_action "SKIP" "Less than 15 min remaining in token reset window — will not launch"
+    ai_log_usage "script/auto-worker-scheduler" "skip" "token budget -- less than 15 min remaining in reset window"
+    exit 0
+  elif [ "$window_remaining_min" -lt 30 ]; then
+    threshold=95
+  elif [ "$window_remaining_min" -lt 45 ]; then
+    threshold=90
+  elif [ "$window_remaining_min" -lt 60 ]; then
+    threshold=80
+  elif [ "$window_remaining_min" -lt 120 ]; then
+    threshold=75
+  else
+    threshold=65
+  fi
+
+  # Compare usage_pct against threshold (integer comparison via python3)
+  if command -v python3 >/dev/null 2>&1; then
+    over_threshold=$(python3 -c "
+pct = float('${usage_pct}' or '0')
+thr = float('${threshold}')
+print('true' if pct >= thr else 'false')
+")
+  else
+    over_threshold="false"
+  fi
+
+  if [ "$over_threshold" = "true" ]; then
+    log_action "SKIP" "Token usage ${usage_pct}% >= threshold ${threshold}% (${window_remaining_min} min remaining in window)"
+    ai_log_usage "script/auto-worker-scheduler" "skip" "token budget at ${usage_pct}% (threshold ${threshold}%)"
+    exit 0
+  fi
+
+  log_action "OK" "Token gate passed: ${usage_pct}% used, threshold ${threshold}% (${window_remaining_min} min remaining)"
+fi
+
+# ---------------------------------------------------------------------------
+# Gate 4: Determine cadence (informational — actual cron cadence managed by
+# CronCreate; this script just logs the recommendation)
+# ---------------------------------------------------------------------------
+
+recommended_cadence="2hr"
+if [ -f "$LAST_RUN_JSON" ] && command -v jq >/dev/null 2>&1; then
+  completed_count=$(jq '.completed | length' "$LAST_RUN_JSON" 2>/dev/null || echo "0")
+  if [ "$completed_count" -gt "0" ]; then
+    recommended_cadence="30min"
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# Gate 5: dangerously_skip_permissions is REQUIRED
+# ---------------------------------------------------------------------------
+# A headless `claude --print` worker has no way to answer interactive
+# permission prompts — without skip-permissions it stalls indefinitely and
+# does no work. Require explicit opt-in rather than launching a worker that
+# can only hang.
+
+skip_perms=$(json_field "$TOKEN_BUDGET_JSON" "auto_worker.dangerously_skip_permissions")
+if [ "$skip_perms" != "true" ]; then
+  log_action "SKIP" "auto_worker.dangerously_skip_permissions is not true — a headless (--print) worker cannot answer permission prompts and would stall. Set it to true in token-budget.json to enable."
+  ai_log_usage "script/auto-worker-scheduler" "skip" "dangerously_skip_permissions not enabled -- headless worker requires it"
+  exit 0
+fi
+
+AUTO_WORKER_PROMPT="Run the auto-worker for this repo.
+
+Instructions:
+1. Read TODO.md and collect all items tagged \`[auto]\` or \`[auto:last]\`.
+2. If no \`[auto]\` items exist, exit cleanly with a brief log entry.
+3. Plan execution order as a dependency graph — do NOT follow TODO list order.
+   - Items without dependencies on each other may run in parallel (branch out when the work is self-contained enough to isolate).
+   - \`[auto:last]\` items run only after all \`[auto]\` items complete or are skipped.
+4. For each item:
+   - Execute the task.
+   - Mark it \`[x]\` in TODO.md on completion.
+   - Add any discovered follow-up tasks as new TODO items; tag \`[auto]\` only if they meet the eligibility criteria in standards/tooling/auto-worker-eligibility.md.
+5. Do NOT touch items that are not tagged \`[auto]\` or \`[auto:last]\`.
+6. At the end, write a one-paragraph summary of what was done, skipped, and added to TODO."
+
+# Write the prompt to a file and feed it to claude via stdin. This avoids the
+# quoting/newline hazards of passing a multi-line prompt as a CLI argument —
+# the previous Windows path crammed the whole prompt (newlines, quotes,
+# backticks) into a single PowerShell -ArgumentList string, which produced a
+# broken command that launched nothing while still logging "LAUNCHED".
+mkdir -p "$(dirname "$PROMPT_FILE")"
+printf '%s\n' "$AUTO_WORKER_PROMPT" > "$PROMPT_FILE"
+
+# ---------------------------------------------------------------------------
+# Dry run: log what would happen, spawn nothing.
+# ---------------------------------------------------------------------------
+if [ "$DRY_RUN" = "1" ]; then
+  log_action "DRY-RUN" "All gates passed. Would launch: claude --dangerously-skip-permissions --print < ${PROMPT_FILE} > ${STDOUT_LOG} (cadence recommendation: ${recommended_cadence})"
+  ai_log_usage "script/auto-worker-scheduler" "dry-run" "all gates passed -- would launch auto-todo-worker"
+  exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Launch: run auto-todo-worker as a detached background process.
+# Output is ALWAYS redirected to STDOUT_LOG/STDERR_LOG so a failed or empty
+# run leaves a trace (the previous Windows path captured nothing).
+# ---------------------------------------------------------------------------
+
+log_action "LAUNCH" "Launching auto-todo-worker (cadence recommendation: ${recommended_cadence})"
+ai_log_usage "script/auto-worker-scheduler" "launch" "launching auto-todo-worker"
+
+launch_pid=""
+if [[ "${OSTYPE:-}" == "msys" ]] || [[ "${OSTYPE:-}" == "cygwin" ]] || \
+   [[ "${OS:-}" == "Windows_NT" ]]; then
+  # Windows via Git Bash. Start-Process detaches the worker from this hook's
+  # shell so it outlives the Stop hook. -RedirectStandardInput feeds the
+  # prompt file (no fragile arg quoting); -RedirectStandardOutput/Error
+  # capture the run; -PassThru returns the REAL worker PID (the old code
+  # logged the wrapper job's PID via `$!`, which was meaningless).
+  # Note: stdout and stderr MUST be different files — Start-Process rejects
+  # redirecting both to the same path.
+  abs_prompt="$(cygpath -w "$PROMPT_FILE" 2>/dev/null || printf '%s' "${PWD}/${PROMPT_FILE}")"
+  abs_stdout="$(cygpath -w "$STDOUT_LOG" 2>/dev/null || printf '%s' "${PWD}/${STDOUT_LOG}")"
+  abs_stderr="$(cygpath -w "$STDERR_LOG" 2>/dev/null || printf '%s' "${PWD}/${STDERR_LOG}")"
+  abs_cwd="$(cygpath -w "$PWD" 2>/dev/null || printf '%s' "${PWD}")"
+  launch_pid=$(powershell -NoProfile -Command "
+    \$p = Start-Process -FilePath 'claude' \
+      -ArgumentList '--dangerously-skip-permissions','--print' \
+      -RedirectStandardInput '${abs_prompt}' \
+      -RedirectStandardOutput '${abs_stdout}' \
+      -RedirectStandardError  '${abs_stderr}' \
+      -WorkingDirectory '${abs_cwd}' \
+      -NoNewWindow -PassThru
+    \$p.Id" 2>/dev/null | tr -d '[:space:]') || true
+else
+  # Unix / macOS / WSL2: feed prompt via stdin, capture output, detach.
+  nohup claude --dangerously-skip-permissions --print \
+    < "$PROMPT_FILE" > "$STDOUT_LOG" 2>&1 &
+  launch_pid=$!
+fi
+
+if [ -n "${launch_pid:-}" ]; then
+  log_action "LAUNCHED" "Background worker PID ${launch_pid} — output -> ${STDOUT_LOG}"
+  ai_log_usage "script/auto-worker-scheduler" "launched" "worker PID ${launch_pid}"
+else
+  log_action "ERROR" "Launch returned no PID — worker likely failed to start. Check ${STDERR_LOG}."
+  ai_log_usage "script/auto-worker-scheduler" "error" "launch returned no PID"
+fi
+exit 0

data/tests/contractor_entity_create.rb

@@ -1,19 +1,19 @@
-require_relative 'local_libs'
-
-api = Ecoportal::API::GraphQL.new
-response = api.createContractorEntity(input: {
-  name: "Caras Galathon",
-  active: true,
-  approved: true,
-  associatedPeopleIds: [
-    "5adfbef76fb80400047535b3"
-  ],
-  leadContractorIds: [
-    "5adfbef76fb80400047535b3"
-  ],
-  clientMutationId: ""
-})
-
-if response.success? && entity = response.item
-  puts "Created contractor entity '#{entity.name}' (approved? #{entity.approved})"
-end
+require_relative 'local_libs'
+
+api = Ecoportal::API::GraphQL.new
+response = api.createContractorEntity(input: {
+  name:                "Caras Galathon",
+  active:              true,
+  approved:            true,
+  associatedPeopleIds: [
+    "5adfbef76fb80400047535b3"
+  ],
+  leadContractorIds:   [
+    "5adfbef76fb80400047535b3"
+  ],
+  clientMutationId:    ""
+})
+
+if response.success? && (entity = response.item)
+  puts "Created contractor entity '#{entity.name}' (approved? #{entity.approved})"
+end

data/tests/contractor_entity_udpate.rb

@@ -1,20 +1,20 @@
-require_relative 'local_libs'
-
-api = Ecoportal::API::GraphQL.new
-response = api.contractorEntity.update(input: {
-  id: "62b04d83fa9170001d3d303f",
-  name: "Caras Galathon",
-  active: true,
-  approved: true,
-  # associatedPeopleIds: [
-  #   "5adfbef76fb80400047535b3"
-  # ],
-  leadContractorIds: {
-    additions: ["5adfbef76fb80400047535b3"]
-  },
-  clientMutationId: ""
-})
-
-if response.success? && entity = response.item
-  puts "Updated contractor entity '#{entity.name}' (approved? #{entity.approved})"
-end
+require_relative 'local_libs'
+
+api = Ecoportal::API::GraphQL.new
+response = api.contractorEntity.update(input: {
+  id:                "62b04d83fa9170001d3d303f",
+  name:              "Caras Galathon",
+  active:            true,
+  approved:          true,
+  # associatedPeopleIds: [
+  #   "5adfbef76fb80400047535b3"
+  # ],
+  leadContractorIds: {
+    additions: ["5adfbef76fb80400047535b3"]
+  },
+  clientMutationId:  ""
+})
+
+if response.success? && (entity = response.item)
+  puts "Updated contractor entity '#{entity.name}' (approved? #{entity.approved})"
+end

data/tests/dump_page_model.rb

@@ -0,0 +1,74 @@
+require_relative 'local_libs'
+require 'json'
+require 'fileutils'
+
+# Dump a page's GraphQL model (the raw CommonPageUnion doc) to a JSON file, so a real page
+# can be captured as a spec fixture / stub. Run it BEFORE and AFTER a submit/sign_off (or any
+# mutation) to capture both states and diff them — the dumps double as regression fixtures.
+#
+# Usage (run in an env where the GraphQL connection is configured, like the other tests/):
+#   ruby tests/dump_page_model.rb <PAGE_ID> [--out PATH] [--stage NAME_OR_ID] [--label before|after]
+#
+# Examples:
+#   # capture the TOOCS page before submitting
+#   ruby tests/dump_page_model.rb 6a3225532b97b00073c23aa8 --label before
+#   # ...run the case live (or a manual updatePage)...
+#   # capture it after
+#   ruby tests/dump_page_model.rb 6a3225532b97b00073c23aa8 --label after
+#   # then diff the two JSON files to see exactly what the submit changed.
+#
+# Default output path: spec/fixtures/pages/<page_id>[_<label>].json
+#
+# A --stage NAME_OR_ID also prints the StageView's stage id (the value that becomes stageId on
+# a submit) so you can confirm the right stage was resolved.
+
+def parse_args(argv)
+  opts = { page_id: nil, out: nil, stage: nil, label: nil }
+  rest = argv.dup
+  opts[:page_id] = rest.shift
+  until rest.empty?
+    flag = rest.shift
+    case flag
+    when '--out'   then opts[:out]   = rest.shift
+    when '--stage' then opts[:stage] = rest.shift
+    when '--label' then opts[:label] = rest.shift
+    else
+      warn "Unknown argument: #{flag}"
+    end
+  end
+  opts
+end
+
+opts = parse_args(ARGV)
+
+unless opts[:page_id]
+  warn 'Usage: ruby tests/dump_page_model.rb <PAGE_ID> [--out PATH] [--stage NAME_OR_ID] [--label before|after]'
+  exit 1
+end
+
+default_dir  = File.expand_path('../spec/fixtures/pages', __dir__)
+default_name = "#{[opts[:page_id], opts[:label]].compact.join('_')}.json"
+out_path     = opts[:out] || File.join(default_dir, default_name)
+
+api  = Ecoportal::API::GraphQL.new
+page = api.pages.get(opts[:page_id], stage_id: opts[:stage])
+
+if page.nil?
+  warn "Could not fetch page '#{opts[:page_id]}'"
+  exit 2
+end
+
+# StageView delegates #doc to the underlying full page; dump the full page doc either way.
+doc = page.respond_to?(:doc) ? page.doc : page.instance_variable_get(:@page)&.doc
+
+FileUtils.mkdir_p(File.dirname(out_path))
+File.write(out_path, JSON.pretty_generate(doc))
+
+puts "Dumped page '#{opts[:page_id]}' → #{out_path}"
+puts "  name:     #{page.respond_to?(:name) ? page.name : '(n/a)'}"
+puts "  patchVer: #{page.respond_to?(:patchVer) ? page.patchVer : '(n/a)'}"
+if opts[:stage]
+  resolved = page.respond_to?(:current_stage_id) ? page.current_stage_id : nil
+  puts "  stage '#{opts[:stage]}' → stageId that a submit would target: #{resolved.inspect}"
+end
+puts 'Tip: capture --label before and --label after a submit, then diff the two JSON files.'

data/tests/loc_structure_get.rb

@@ -1,9 +1,8 @@
 require_relative 'local_libs'
 
-STRUCT_ID = "592642a4ae0c6a00236b110d" # mini test
+STRUCT_ID = "592642a4ae0c6a00236b110d".freeze # mini test
 # STRUCT_ID = "626745bcba616a001f7e5011" # wcc
 
-
 api = Ecoportal::API::GraphQL.new
 api.currentOrganization.locationStructure(id: STRUCT_ID).tap do |tree|
   puts "'#{tree.name}' Structure (#{tree.id})"

data/tests/loc_structure_update.rb

@@ -1,51 +1,51 @@
-require_relative 'local_libs'
-
-STRUCT_ID = "592642a4ae0c6a00236b110d" # mini test
-# STRUCT_ID = "626745bcba616a001f7e5011" # wcc
-
-api = Ecoportal::API::GraphQL.new
-
-# DESIRED DESIGN: (to review: it might be that draft tree model already stores the commands?)
-# tree = api.currentOrganization.LocationStructure(id: STRUCT_ID)
-# node = tree.node["SYDNEY"]
-# node.name = "Sydney City"
-# tree.node["UPS"].move("AUCKLAND") # or tree.move("UPS", to: "AUCKLAND")
-# tree.node["FFFF."].delete
-# tree.node["UPS"].insert("CHILD", name: "Child").insert("GRAND CHILD", name: "Grand Child")
-# tree.change_commands # => return Ecoportal::API::GraphQL::Input::ApplyCommands
-
-INPUT = {
-  change: {
-    clientMutationId: "",
-    id: STRUCT_ID,
-    commands: [
-      { update: { nodeId: "SYDNEY", name: "Sydney City" } },
-      { move:   { nodeId: "UPS", parentId: "AUCKLAND" } },
-      { archive: { nodeId: "FFFF." } },
-      { insert: { parentId: "UPS", nodeId: "CHILD", name: "Child" } },
-      { insert: { parentId: "CHILD", nodeId: "GRAND CHILD", name: "Grand Child" } }
-    ]
-  },
-  revert: {
-    clientMutationId: "",
-    id: STRUCT_ID,
-    commands: [
-      { update: { nodeId: "SYDNEY", name: "Sydney" } },
-      { move:   { nodeId: "UPS", parentId: "SUB'TAGs" } },
-      { unarchive: { nodeId: "FFFF." } },
-      { archive: { nodeId: "CHILD" } }
-    ]
-  }
-}
-
-operation = :change
-response = api.locationStructure.applyCommands(input: INPUT[operation])
-
-if response.success? && structure = response.structure
-  puts "Applied '#{operation}' changes to '#{structure.name}' structure:"
-  pp structure.treeify
-end
-
-puts "Some more feedback:"
-#pp response.results.as_json
-pp response.results.map(&:as_json)
+require_relative 'local_libs'
+
+STRUCT_ID = "592642a4ae0c6a00236b110d".freeze # mini test
+# STRUCT_ID = "626745bcba616a001f7e5011" # wcc
+
+api = Ecoportal::API::GraphQL.new
+
+# DESIRED DESIGN: (to review: it might be that draft tree model already stores the commands?)
+# tree = api.currentOrganization.LocationStructure(id: STRUCT_ID)
+# node = tree.node["SYDNEY"]
+# node.name = "Sydney City"
+# tree.node["UPS"].move("AUCKLAND") # or tree.move("UPS", to: "AUCKLAND")
+# tree.node["FFFF."].delete
+# tree.node["UPS"].insert("CHILD", name: "Child").insert("GRAND CHILD", name: "Grand Child")
+# tree.change_commands # => return Ecoportal::API::GraphQL::Input::ApplyCommands
+
+INPUT = {
+  change: {
+    clientMutationId: "",
+    id:               STRUCT_ID,
+    commands:         [
+      { update: { nodeId: "SYDNEY", name: "Sydney City" } },
+      { move:   { nodeId: "UPS", parentId: "AUCKLAND" } },
+      { archive: { nodeId: "FFFF." } },
+      { insert: { parentId: "UPS", nodeId: "CHILD", name: "Child" } },
+      { insert: { parentId: "CHILD", nodeId: "GRAND CHILD", name: "Grand Child" } }
+    ]
+  },
+  revert: {
+    clientMutationId: "",
+    id:               STRUCT_ID,
+    commands:         [
+      { update: { nodeId: "SYDNEY", name: "Sydney" } },
+      { move:   { nodeId: "UPS", parentId: "SUB'TAGs" } },
+      { unarchive: { nodeId: "FFFF." } },
+      { archive: { nodeId: "CHILD" } }
+    ]
+  }
+}.freeze
+
+operation = :change
+response = api.locationStructure.applyCommands(input: INPUT[operation])
+
+if response.success? && (structure = response.structure)
+  puts "Applied '#{operation}' changes to '#{structure.name}' structure:"
+  pp structure.treeify
+end
+
+puts "Some more feedback:"
+#pp response.results.as_json
+pp response.results.map(&:as_json)