ecoportal-api-v2 3.3.1 → 3.3.3

data/CLAUDE.md

@@ -0,0 +1,82 @@
+# CLAUDE.md — ecoportal-api-v2
+
+AI agent instructions for this repository.
+
+**Cross-cutting architecture context lives in `ecoportal-api-graphql` — see its `CLAUDE.md` and `.claude/` folder for the full dependency map, project history, and shared skills.**
+
+---
+
+## Repository Role
+
+`ecoportal-api-v2` is the **REST API v2 gem**, extending `ecoportal-api` with a rich content model layer (pages, registers, people, S3 file handling). It provides the `Ecoportal::API::V2` and `Ecoportal::API::Common::Content` namespaces.
+
+**Position in chain:**
+```
+ecoportal-api
+      ↓
+ecoportal-api-v2       ← THIS REPO
+      ↓
+ecoportal-api-graphql
+      ↓
+eco-helpers
+```
+
+**Remote:** https://gitlab.ecoportal.co.nz/oscar/ecoportal-api-v2.git
+
+---
+
+## Key Folder Layout
+
+```
+lib/ecoportal/api/
+  common/
+    concerns/          Benchmarkable, Threadable mixins
+    content/           Core model infrastructure (see below)
+  v2/
+    page/              Page model — sections, stages, components, forces, permissions
+    page/component/    All field types (text, number, date, selection, files, geo, etc.)
+    pages/             Pages collection, stage results, tasks
+    registers/         Register models — search results, stage/page results
+    people/            V2 people endpoint
+    s3/                S3 file upload/download infrastructure
+```
+
+### `Common::Content` — the model engine
+
+The most complex part of this gem. Key classes:
+
+- `DoubleModel` — two-layer model (a "live" doc and a "patch" doc) with attribute DSL, diffing, nesting, and change tracking. Almost all V2 models inherit from this.
+- `CollectionModel` — ordered collection with upsert/delete/mutation support.
+- `ClassHelpers` — `class_resolver` macro for injectable class references (pattern shared with `ecoportal-api-graphql`).
+- `DocHelpers`, `ModelHelpers`, `IncluderHelpers` — utility mixins for model construction.
+
+---
+
+## Namespace
+
+- `Ecoportal::API::V2` — v2 REST resources
+- `Ecoportal::API::Common::Content` — shared model infrastructure (consumed downstream)
+- `Ecoportal::API::Common::Concerns` — threading and benchmarking mixins
+
+---
+
+## Key Concerns
+
+- `DoubleModel` is the foundational abstraction — understand it before modifying any V2 model.
+- `Common::Content::ClassHelpers` mirrors the `ClassHelpers` in `ecoportal-api-graphql` — changes to one may need mirroring in the other.
+- S3 upload is async with polling (`s3/files/poll.rb`) — timing-sensitive code.
+
+---
+
+## Backwards Compatibility
+
+`eco-helpers` and `ecoportal-api-graphql` both depend on this gem. Changes to `Common::Content::*` or `V2::Page::*` interfaces must be checked against usage in both downstream gems before committing.
+
+---
+
+## Running Tests
+
+```bash
+bundle install
+bundle exec rspec
+```

data/ecoportal-api-v2.gemspec

@@ -33,7 +33,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rubocop-rake', '~> 0'
   spec.add_development_dependency 'yard',         '~> 0.9'
 
-  spec.add_dependency 'ecoportal-api', '~> 0.10', '>= 0.10.12'
+  spec.add_dependency 'ecoportal-api', '~> 0.10', '>= 0.10.16'
   spec.add_dependency 'mime-types',    '~> 3.5',  '>= 3.5.2'
 end
 

data/lib/ecoportal/api/common/concerns/benchmarkable.rb

@@ -16,6 +16,7 @@ module Ecoportal
 
           def benchmarking(ref = nil, units: 1, print: false, &block)
             return yield unless benchmark_enabled?
+
             benchmark_mem(ref, units: units, print: false) do
               benchmark_time(ref, units: units, print: false, &block)
             end.tap do

data/lib/ecoportal/api/common/content/double_model/attributable/nesting/cascaded_callback.rb

@@ -178,7 +178,7 @@ module Ecoportal::API::Common::Content::DoubleModel::Attributable::Nesting
           nested_attrs: _cascaded_attributes.keys,
           attributes:   {}
         }.merge(trace || {}).tap do |out_trace|
-          _cascaded_attributes.each.with_object(out_trace) do |out, (attribute, obj_k)|
+          _cascaded_attributes.each.with_object(out_trace) do |(attribute, obj_k), out|
             next unless (obj = send(attribute))
 
             obj_k_path = key_path.dup.push(obj_k)

data/lib/ecoportal/api/common/content/double_model/double_doc/linkable_doc.rb

@@ -35,6 +35,7 @@ module Ecoportal
               def as_json
                 doc
               end
+              alias_method :to_h, :as_json
 
               def print_pretty
                 puts JSON.pretty_generate(as_json)

data/lib/ecoportal/api/v2/s3/files/batch_upload.rb

@@ -3,7 +3,9 @@ module Ecoportal
     class V2
       class S3
         class Files
-          # Class service to upload multiple files in one go
+          # Class service to upload multiple files in one go.
+          # Full cycle: from local files to the org file manager.
+          # @note it uploads to S3, and converts it into a file container as well.
           class BatchUpload
             include Ecoportal::API::Common::Concerns::Benchmarkable
             include Ecoportal::API::Common::Concerns::Threadable

data/lib/ecoportal/api/v2_version.rb

@@ -1,5 +1,5 @@
 module Ecoportal
   module API
-    GEM2_VERSION = '3.3.1'.freeze
+    GEM2_VERSION = '3.3.3'.freeze
   end
 end

data/scripts/auto-worker-scheduler.sh

@@ -0,0 +1,307 @@
+#!/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"
+
+# ---------------------------------------------------------------------------
+# 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
+}
+
+# ---------------------------------------------------------------------------
+# 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 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 opt-in
+# ---------------------------------------------------------------------------
+
+skip_perms=$(json_field "$TOKEN_BUDGET_JSON" "auto_worker.dangerously_skip_permissions")
+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."
+
+CLAUDE_FLAGS="--print \"${AUTO_WORKER_PROMPT}\""
+if [ "$skip_perms" = "true" ]; then
+  CLAUDE_FLAGS="--dangerously-skip-permissions --print \"${AUTO_WORKER_PROMPT}\""
+fi
+
+# ---------------------------------------------------------------------------
+# Launch: run auto-todo-worker as a background process
+# ---------------------------------------------------------------------------
+
+log_action "LAUNCH" "Launching auto-todo-worker (cadence recommendation: ${recommended_cadence})"
+ai_log_usage "script/auto-worker-scheduler" "launch" "launching auto-todo-worker"
+
+if [[ "${OSTYPE:-}" == "msys" ]] || [[ "${OSTYPE:-}" == "cygwin" ]] || \
+   [[ "${OS:-}" == "Windows_NT" ]]; then
+  # Windows via Git Bash / WSL
+  # Use PowerShell Start-Process to launch detached from the current terminal
+  powershell -Command "Start-Process -FilePath 'claude' \
+    -ArgumentList '${CLAUDE_FLAGS}' \
+    -WorkingDirectory '${PWD}' \
+    -NoNewWindow" &
+  launch_pid=$!
+else
+  # Unix / macOS / WSL2
+  if [ "$skip_perms" = "true" ]; then
+    nohup claude --dangerously-skip-permissions --print "run auto worker" \
+      > ".ai-assistance/local/auto-worker-stdout.log" 2>&1 &
+  else
+    nohup claude --print "run auto worker" \
+      > ".ai-assistance/local/auto-worker-stdout.log" 2>&1 &
+  fi
+  launch_pid=$!
+fi
+
+log_action "LAUNCHED" "Background PID ${launch_pid:-unknown} — flags: ${CLAUDE_FLAGS}"
+exit 0

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ecoportal-api-v2
 version: !ruby/object:Gem::Version
-  version: 3.3.1
+  version: 3.3.3
 platform: ruby
 authors:
 - Oscar Segura
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-06-11 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pry
@@ -135,7 +134,7 @@ dependencies:
         version: '0.10'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.10.12
+        version: 0.10.16
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -145,7 +144,7 @@ dependencies:
         version: '0.10'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.10.12
+        version: 0.10.16
 - !ruby/object:Gem::Dependency
   name: mime-types
   requirement: !ruby/object:Gem::Requirement
@@ -166,13 +165,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 3.5.2
-description:
 email:
 - oscar@ecoportal.co.nz
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".ai-assistance/code/double_model_patterns.md"
+- ".ai-assistance/conventions/code-working-tree-protocol.md"
+- ".ai-assistance/scripts/token-logger.js"
+- ".ai-assistance/scripts/token-report.ts"
+- ".ai-assistance/scripts/token-session-start.js"
+- ".ai-assistance/skills/eP_AI_Manager/SKILL.md"
+- ".ai-assistance/token-budget.json"
+- ".claude/settings.json"
 - ".gitignore"
 - ".markdownlint.json"
 - ".rspec"
@@ -180,6 +186,7 @@ files:
 - ".ruby-version"
 - ".yardopts"
 - CHANGELOG.md
+- CLAUDE.md
 - Gemfile
 - LICENSE
 - README.md
@@ -329,12 +336,12 @@ files:
 - lib/ecoportal/api/v2/s3/files/poll_status.rb
 - lib/ecoportal/api/v2/s3/upload.rb
 - lib/ecoportal/api/v2_version.rb
+- scripts/auto-worker-scheduler.sh
 homepage: https://www.ecoportal.com
 licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -349,8 +356,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.23
-signing_key:
+rubygems_version: 4.0.8
 specification_version: 4
 summary: A collection of helpers for interacting with the ecoPortal MS's V2 API
 test_files: []