ecoportal-api-v2 3.3.2 → 3.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fcf0d1bcb9682c389d37e23c34f5e8b358fec8867dcc42da783279e9d7b3de85
-  data.tar.gz: 62f6710a5f91ad24960ccd6cd03b83703de067e6cbcd7f49f2814ed792e5b287
+  metadata.gz: f6d039e12072cb81b7229475b99b9f8d460375679130af1fe9272a2d2c1241ad
+  data.tar.gz: 347a85aa42ac89cffe29579abc90d35a4e30e16825a73b30b544cfe57abc3948
 SHA512:
-  metadata.gz: f398d701389d9a3f705385a86ed7f14bf055b77e244fef3f735fe5d63d85974d305520a77bb142506c8ede0d7ab2436fe520098c859fba950f7c18ed65594c8e
-  data.tar.gz: b01280b46c5168ab31d510680ee8d46b650c0c25dc4540784fff591a2160fe848f7e6d7a365259ddaea53199f4e1381eca6aa8d0a391d89e134bddf2206bb9d0
+  metadata.gz: f1a68e3d165c7fbb18d1136b423c79250561de8d29c87851a001a7cd7f431ccbef872d3c80b3b2ae4769faf491e985398cfb89962b71186c9efa22efe8ceda1f
+  data.tar.gz: 0a19c1a759679221430cf50897ba75da1c65b594684a35e06aa4e8ab1b357fbf267eca53aab4d5805c18ce161d7c5dea988ec957d7a627eadc50751529935b13

data/.ai-assistance/code/double_model_patterns.md

@@ -0,0 +1,133 @@
+# Code Spec: DoubleModel Patterns
+
+**Scope:** Core patterns in `ecoportal-api-v2` that downstream gems (especially `ecoportal-api-graphql`) depend on.
+**Last updated:** 2026-06-05
+
+---
+
+## DoubleModel Architecture
+
+`DoubleModel` is the base class for all model objects. It stores data in two hashes:
+- `@doc` — current state (mutated by setters)
+- `@original_doc` — snapshot at initialization time (never mutated)
+
+Both are created via `JSON.parse(doc.to_json)` — meaning **keys are always STRING**.
+This matters for any code that compares current vs original documents.
+
+```ruby
+def initialize(doc = {}, parent: self, key: nil, read_only: ...)
+  @doc          = JSON.parse(doc.to_json)   # string keys
+  @original_doc = JSON.parse(@doc.to_json)  # string keys, snapshot
+end
+```
+
+### Key rule: `change_data` uses symbol keys for comparison
+
+`HashDiffNesting#change_data` converts keys to symbols (`key.to_sym`) before comparing.
+If you call it with hashes that have **string keys** (as `DoubleModel` docs do), the lookup
+`b.key?(:name)` will ALWAYS be false (the hash has `'name'`, not `:name`).
+
+**Consequence:** Always normalise both `curr` and `prev` to symbol keys before passing to
+`change_data`. See `ecoportal-api-graphql`'s `DiffService#classic_diff` fix.
+
+---
+
+## Field Definition Macros
+
+| Macro | Effect |
+|-------|--------|
+| `passkey :fieldName` | ID field — registered as `key_method`, used for array lookups and `get_id` |
+| `passthrough :fieldName` | Getter + setter mapping to `@doc['fieldName']` |
+| `passboolean :fieldName` | Same as passthrough, coerces to Boolean |
+| `passarray :fieldName` | Creates an `ArrayModel` wrapping `@doc['fieldName']` |
+| `passdate :fieldName` | DateTime passthrough |
+| `embeds_one :fieldName, klass:` | Lazy single-object embed; registers as cascaded attribute |
+| `embeds_many :fieldName, klass:` | Lazy collection embed; registers as cascaded attribute |
+| `root!` | Marks the class as a "root" (lookup-only) object — excluded from parent cascaded diffs |
+| `read_only!` | Marks the class as read-only |
+
+### Lazy embed initialisation (IMPORTANT)
+
+`embeds_one` and `embeds_many` getters auto-initialize `@doc['fieldName']` to `{}` or `[]`
+when accessed for the first time (`doc[obj_k] ||= multiple ? [] : {}`).
+
+**Side effect:** Accessing any embedded field mutates `@doc`. Any code that calls `as_json`
+or reads `@doc` AFTER a getter call will see auto-created empty objects, even if they were
+not in the original hash. This is relevant when computing diffs.
+
+---
+
+## Cascaded Attributes
+
+Cascaded attributes are embedded fields registered via `embeds_one` / `embeds_many`.
+They appear in `_cascaded_attributes` as `{method_name => doc_key}`.
+
+`_cascaded_doc_keys` returns the string doc keys of all cascaded attributes — used by
+`DiffService` to strip them from the flat diff before comparison.
+
+### `cascaded_reduce` (v3.3.3+)
+
+Iterates over the subject and all its cascaded attribute objects:
+
+```ruby
+subject.cascaded_reduce(init) do |result, obj, key, key_path, trace|
+  # key_path = [] for top-level subject
+  # key_path = ['fieldName'] for first-level embeds
+  ...
+end
+```
+
+**Ruby 3.x compatibility note:** The block parameter pattern in `_cascaded_attributes_trace`
+was `|out, (attribute, obj_k)|` (WRONG — swapped) and was corrected to `|(attribute, obj_k), out|`
+in commit `6a2b1b5`. If you see TypeError about the trace hash being passed to `send`,
+check this method.
+
+---
+
+## `as_update` on DoubleModel (ecoportal-api-v2)
+
+`DoubleModel` in ecoportal-api-v2 has its own `as_update` (no kwargs). This is DIFFERENT
+from `ecoportal-api-graphql`'s `Common::GraphQL::Model#as_update(**kargs)`.
+
+When `DiffService#diff_reduce` calls `obj.as_update(ignore: [...])`, only call it on objects
+that are `Common::GraphQL::Model` instances (the GraphQL gem's version with keyword args).
+`ArrayModel` and other plain `DoubleModel` subclasses use the no-kwargs version and must be
+skipped.
+
+---
+
+## `ArrayModel` (created by `passarray`)
+
+`passarray :fieldName` creates an `ArrayModel::FieldName` subclass inheriting from
+`Common::Content::ArrayModel < DoubleModel`. It wraps an array of primitive values (IDs, strings).
+
+`ArrayModel` instances:
+- Respond to `as_update` (the ecoportal-api-v2 no-kwargs version)
+- Are registered as cascaded attributes
+- Should NOT be diff'd by `DiffService` (they're ID arrays, not model objects)
+- Their changes are captured via the flat diff (`passarray` fields are scalar arrays)
+
+---
+
+## `HashHelpers` (in DoubleModel)
+
+Defines `dig_path?`, `dig_set!`, `dig_delete!` for nested hash navigation.
+These are NOT included in plain service classes. If your class needs them, include
+`Ecoportal::API::Common::Content::DoubleModel::HashHelpers::InstanceMethods` or
+define them locally (see `ecoportal-api-graphql`'s `HashDiffNesting` for a copy).
+
+---
+
+## Known Issues / Gotchas
+
+1. **String vs symbol keys**: `DoubleModel` always uses string keys in `@doc` / `@original_doc`.
+   Any comparison against symbol keys will silently fail to match. Always normalise before comparing.
+
+2. **Lazy embed mutation**: Accessing `model.fieldName` on a model that didn't have that field
+   in the original doc adds `'fieldName' => {}` to `@doc`. This pollutes `as_json` output.
+
+3. **`cascaded_reduce` block parameters**: Must use `|(element, obj_k), accumulator|` pattern
+   (not `|accumulator, (element, obj_k)|`). Ruby 3.x strict argument handling exposed this.
+
+4. **`as_update` in ecoportal-api-v2 takes no kwargs**. Only `ecoportal-api-graphql`'s
+   `Common::GraphQL::Model#as_update` accepts `ignore:` keyword argument.

data/.ai-assistance/conventions/code-working-tree-protocol.md

@@ -0,0 +1,176 @@
+# Code Working Tree Protocol
+
+When Claude Code needs to make changes to files **outside** `bridge/inbox/`, it must
+follow this protocol. This prevents Code's changes from mixing with in-progress CoWork
+edits and ensures a clean, traceable commit history.
+
+---
+
+## When this applies
+
+Any time Code intends to modify files in the working tree that are not bridge task files
+(i.e., not `.ai-assistance/bridge/inbox/` or `.ai-assistance/bridge/outbox/`).
+
+This includes: editing source files, updating documentation, changing scripts,
+modifying capabilities files, etc.
+
+---
+
+## Protocol
+
+### 0. Check for a lock
+
+```bash
+cat .ai-assistance/bridge/LOCK 2>/dev/null || echo "NO_LOCK"
+```
+
+- **No lock:** proceed to step 1
+- **Lock exists, EXPIRES is in the future:** stop. Tell the user:
+  > "Working tree is locked by [AGENT] ([USER]) since [ACQUIRED], working on: [INTENT].
+  > Expires at [EXPIRES]. Please wait or check if the other session is still active."
+- **Lock exists, EXPIRES is in the past:** stale lock — safe to overwrite, proceed to step 1
+
+---
+
+### 1. Acquire the lock
+
+Write `.ai-assistance/bridge/LOCK` with full watermark:
+
+```
+AGENT: code
+USER: [git config user.name, lowercased]
+ACQUIRED: [ISO 8601 now]
+EXPIRES: [ISO 8601 now + 30 minutes]
+INTENT: [one sentence — what you are about to change and why]
+FILES: [comma-separated list of files you plan to modify]
+```
+
+Example:
+```
+AGENT: code
+USER: oscar
+ACQUIRED: 2026-06-04T10:00:00Z
+EXPIRES: 2026-06-04T10:30:00Z
+INTENT: Update gitlab-mcp.md with new PAT scopes and rotation info
+FILES: .ai-assistance/integrations/gitlab-mcp.md
+```
+
+---
+
+### 2. Check for unstaged changes that overlap with your planned files
+
+```bash
+git status --short
+```
+
+If the working tree is clean, skip to step 3.
+
+If there are unstaged/staged changes, compare them against the files listed in your LOCK:
+
+```bash
+git diff --name-only HEAD
+git diff --cached --name-only
+```
+
+- **No overlap with your FILES:** proceed — the changes are unrelated and won't pollute history
+- **Overlap with one or more of your FILES:** commit the unstaged changes first.
+  Derive the commit message by running `git diff HEAD` on the overlapping files and
+  writing a short imperative summary of what actually changed — do not use a generic
+  message. Format: `wip: <what changed, e.g. "rename .claude to .ai-assistance across scripts">`
+
+```bash
+git add -A
+git commit -m "wip: <derived from actual diff>"
+```
+
+This keeps Code's subsequent commit clean and ensures both sets of changes build
+on the correct base. On a feature branch, `wip:` commits are fine — squash before MR.
+
+---
+
+### 3. Apply your changes
+
+Make the intended file edits. Stay within the scope declared in INTENT and FILES
+when you acquired the lock. If scope expands, update the LOCK file before proceeding.
+
+---
+
+### 4. Commit your changes
+
+```bash
+git add -A
+git commit -m "[descriptive message — what Code changed and why]"
+```
+
+Commit message should be specific enough that a teammate can understand the change
+without reading the diff. Example:
+```
+docs: update gitlab-mcp.md scopes and rotation info for new PAT (April 2027 expiry)
+```
+
+**Commit authorship — developer only by default:**
+
+Commits are authored by the developer alone (git's `user.name` / `user.email` config).
+Do NOT add `Co-Authored-By: Claude ...` to commit messages unless the developer
+explicitly requests it.
+
+Rationale: the commit history is the developer's professional record. Co-authorship is
+opt-in, not opt-out. If the developer wants to attribute AI involvement, they can add
+it themselves or ask Claude to include it for a specific commit.
+
+Before adding any co-authorship attribution, ask:
+> "Would you like to add AI co-authorship to this commit, or keep it as your commit alone?"
+
+Default answer if not asked: **developer only**.
+
+---
+
+### 5. Release the lock
+
+```bash
+rm .ai-assistance/bridge/LOCK
+```
+
+---
+
+## Quick reference
+
+```bash
+# 0. Check lock
+cat .ai-assistance/bridge/LOCK 2>/dev/null || echo "NO_LOCK"
+
+# 1. Acquire lock
+cat > .ai-assistance/bridge/LOCK << EOF
+AGENT: code
+USER: oscar
+ACQUIRED: $(date -u +"%Y-%m-%dT%H:%M:%SZ")
+EXPIRES: $(date -u -d "+30 minutes" +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || date -u -v+30M +"%Y-%m-%dT%H:%M:%SZ")
+INTENT: <what you are changing>
+FILES: <files>
+EOF
+
+# 2. Check for overlapping unstaged changes
+git diff --name-only HEAD && git diff --cached --name-only
+# If any of those files overlap with your planned FILES → commit them first:
+git add -A && git commit -m "wip: <description of CoWork's in-progress work>"
+# If no overlap → skip, proceed directly
+
+# 3. Apply changes
+# ... make edits ...
+
+# 4. Commit your changes
+git add -A && git commit -m "<descriptive message>"
+
+# 5. Release lock
+rm .ai-assistance/bridge/LOCK
+```
+
+---
+
+## Notes
+
+- If Code crashes mid-protocol, the LOCK will expire naturally (30 min timeout)
+- The `wip:` commit prefix signals to teammates that this was an auto-committed
+  in-progress state — safe to squash or amend later
+- This protocol does not apply to bridge task processing (reading inbox, writing outbox)
+  — those are read/write of bridge files only and don't touch the working tree

data/.ai-assistance/scripts/token-logger.js

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+/**
+ * token-logger.js
+ *
+ * Claude Code Stop hook — fires after every AI response turn.
+ * Reads the session transcript, extracts token usage, accumulates weekly totals,
+ * and warns when approaching the project's budget allocation.
+ *
+ * Wired in .claude/settings.json:
+ *   "Stop": [{ "type": "command", "command": "node .ai-assistance/scripts/token-logger.js" }]
+ *
+ * Reads:  stdin (Stop event JSON with session_id, transcript_path, cwd)
+ *         .ai-assistance/token-budget.json
+ *         .ai-assistance/local/kpi/session-<id>.json  (running session state)
+ *         .ai-assistance/local/kpi/weekly-<YYYY-WNN>.json  (weekly totals)
+ *
+ * Writes: .ai-assistance/local/kpi/session-<id>.json  (updated state)
+ *         .ai-assistance/local/kpi/weekly-<YYYY-WNN>.json  (updated totals)
+ *         .ai-assistance/local/kpi/sessions-<YYYY-WNN>.jsonl  (completed turns)
+ */
+
+const fs   = require("fs");
+const path = require("path");
+const os   = require("os");
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function isoWeek(d) {
+  const jan4 = new Date(d.getFullYear(), 0, 4);
+  const startOfWeek = new Date(jan4);
+  startOfWeek.setDate(jan4.getDate() - ((jan4.getDay() + 6) % 7));
+  const weekNum = Math.ceil(((d - startOfWeek) / 86400000 + 1) / 7);
+  return `${d.getFullYear()}-W${String(weekNum).padStart(2, "0")}`;
+}
+
+function loadJson(p, fallback) {
+  try { return JSON.parse(fs.readFileSync(p, "utf8")); }
+  catch { return fallback; }
+}
+
+function saveJson(p, data) {
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(data, null, 2) + "\n", "utf8");
+}
+
+function appendJsonl(p, obj) {
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.appendFileSync(p, JSON.stringify(obj) + "\n", "utf8");
+}
+
+// ── Extract token usage from transcript JSONL ──────────────────────────────
+
+function extractUsageFromTranscript(transcriptPath) {
+  if (!transcriptPath || !fs.existsSync(transcriptPath)) return null;
+
+  let inputTokens = 0, outputTokens = 0, cacheReadTokens = 0, cacheCreateTokens = 0;
+  let toolCalls = 0, turns = 0, found = false;
+
+  try {
+    const lines = fs.readFileSync(transcriptPath, "utf8").split("\n").filter(Boolean);
+    for (const line of lines) {
+      try {
+        const entry = JSON.parse(line);
+        // Extract usage from any entry that has it
+        const usage = entry.usage || entry.message?.usage;
+        if (usage) {
+          inputTokens      += usage.input_tokens              || 0;
+          outputTokens     += usage.output_tokens             || 0;
+          cacheReadTokens  += usage.cache_read_input_tokens   || 0;
+          cacheCreateTokens+= usage.cache_creation_input_tokens|| 0;
+          found = true;
+        }
+        // Count tool uses
+        if (entry.type === "tool_use" || entry.tool_name) toolCalls++;
+        // Count assistant turns
+        if (entry.role === "assistant" || entry.type === "assistant") turns++;
+      } catch { /* skip malformed lines */ }
+    }
+  } catch { return null; }
+
+  if (!found) return null;
+  return { inputTokens, outputTokens, cacheReadTokens, cacheCreateTokens, toolCalls, turns };
+}
+
+// ── Estimate tokens when transcript doesn't have usage data ───────────────
+
+function estimateFromTranscript(transcriptPath) {
+  if (!transcriptPath || !fs.existsSync(transcriptPath)) {
+    return { inputTokens: 0, outputTokens: 0, toolCalls: 0, turns: 0, estimated: true };
+  }
+  let inputChars = 0, outputChars = 0, toolCalls = 0, turns = 0;
+  try {
+    const lines = fs.readFileSync(transcriptPath, "utf8").split("\n").filter(Boolean);
+    for (const line of lines) {
+      try {
+        const entry = JSON.parse(line);
+        const content = JSON.stringify(entry.content || entry.text || "");
+        if (entry.role === "user" || entry.type === "user")           { inputChars += content.length; }
+        if (entry.role === "assistant" || entry.type === "assistant") { outputChars += content.length; turns++; }
+        if (entry.type === "tool_use" || entry.tool_name)             { toolCalls++; inputChars += 500 * 4; }
+      } catch { /* skip */ }
+    }
+  } catch {}
+  return {
+    inputTokens:  Math.round(inputChars / 4),
+    outputTokens: Math.round(outputChars / 4),
+    cacheReadTokens: 0, cacheCreateTokens: 0,
+    toolCalls, turns, estimated: true
+  };
+}
+
+// ── Main ───────────────────────────────────────────────────────────────────
+
+async function main() {
+  let event = {};
+  try {
+    const raw = fs.readFileSync("/dev/stdin", "utf8");
+    event = JSON.parse(raw);
+  } catch { /* no stdin or parse error — use empty event */ }
+
+  const cwd            = event.cwd || process.cwd();
+  const sessionId      = event.session_id || `unknown-${Date.now()}`;
+  const transcriptPath = event.transcript_path;
+
+  const budgetFile  = path.join(cwd, ".ai-assistance", "token-budget.json");
+  const kpiDir      = path.join(cwd, ".ai-assistance", "local", "kpi");
+  const weekId      = isoWeek(new Date());
+  const sessionFile = path.join(kpiDir, `session-${sessionId}.json`);
+  const weeklyFile  = path.join(kpiDir, `weekly-${weekId}.json`);
+  const turnLogFile = path.join(kpiDir, `sessions-${weekId}.jsonl`);
+
+  const budget  = loadJson(budgetFile, {});
+  const project = (budget.project?.name || path.basename(cwd));
+  const priority= (budget.project?.priority || "medium");
+  const targetPct = (budget.weekly_quota?.target_utilization_pct || 75) / 100;
+  const warnAt    = (budget.session_logging?.warn_at_pct || 80) / 100;
+
+  // Extract usage from transcript
+  const transcriptUsage = extractUsageFromTranscript(transcriptPath)
+    || estimateFromTranscript(transcriptPath);
+
+  // Load previous session state (accumulate across turns in a session)
+  const prevSession = loadJson(sessionFile, {
+    session_id: sessionId, project, priority,
+    started_at: new Date().toISOString(),
+    week_id: weekId,
+    input_tokens: 0, output_tokens: 0,
+    cache_read_tokens: 0, cache_create_tokens: 0,
+    tool_calls: 0, turns: 0, estimated: false,
+  });
+
+  // Use transcript totals (they accumulate naturally) not deltas
+  const sessionNow = {
+    ...prevSession,
+    input_tokens:       transcriptUsage.inputTokens,
+    output_tokens:      transcriptUsage.outputTokens,
+    cache_read_tokens:  transcriptUsage.cacheReadTokens  || 0,
+    cache_create_tokens:transcriptUsage.cacheCreateTokens || 0,
+    tool_calls:         transcriptUsage.toolCalls,
+    turns:              transcriptUsage.turns,
+    estimated:          transcriptUsage.estimated || false,
+    last_updated_at:    new Date().toISOString(),
+  };
+
+  saveJson(sessionFile, sessionNow);
+
+  // Update weekly totals — replace session contribution (re-compute from sessions)
+  const weekly = loadJson(weeklyFile, { week_id: weekId, projects: {}, total_tokens: 0 });
+  const sessionTotal = sessionNow.input_tokens + sessionNow.output_tokens;
+  const prevContrib  = (weekly.projects[sessionId]?.tokens || 0);
+  weekly.projects[sessionId] = {
+    project, priority, tokens: sessionTotal,
+    tool_calls: sessionNow.tool_calls, turns: sessionNow.turns,
+    updated_at: new Date().toISOString()
+  };
+  weekly.total_tokens = Object.values(weekly.projects).reduce((s, p) => s + p.tokens, 0);
+  saveJson(weeklyFile, weekly);
+
+  // Log the turn to the weekly JSONL (for cross-session analysis)
+  appendJsonl(turnLogFile, {
+    ts: new Date().toISOString(), session_id: sessionId, project, priority, week_id: weekId,
+    turn_tokens: sessionTotal - prevContrib,
+    session_total_tokens: sessionTotal,
+    tool_calls: sessionNow.tool_calls,
+    estimated: sessionNow.estimated,
+  });
+
+  // ── Budget warnings ────────────────────────────────────────────────────
+
+  const totalTokens = budget.weekly_quota?.total_tokens;
+  if (totalTokens) {
+    const usedPct = weekly.total_tokens / totalTokens;
+    const targetTokens = totalTokens * targetPct;
+
+    // Priority-based soft allocation
+    const weights  = budget.project_allocation?.priority_weights || { high: 50, medium: 30, low: 20 };
+    const myWeight = (weights[priority] || 30) / 100;
+    const myBudget = totalTokens * targetPct * myWeight;
+    const myUsed   = Object.values(weekly.projects)
+      .filter(p => p.project === project)
+      .reduce((s, p) => s + p.tokens, 0);
+    const myPct = myBudget > 0 ? myUsed / myBudget : 0;
+
+    if (usedPct >= warnAt) {
+      process.stderr.write(
+        `\n[token-budget] ⚠  Week ${weekId}: ${Math.round(usedPct * 100)}% of quota used` +
+        ` (${weekly.total_tokens.toLocaleString()}/${totalTokens.toLocaleString()} tokens)` +
+        ` — target was ${Math.round(targetPct * 100)}%\n`
+      );
+    }
+    if (myPct >= warnAt) {
+      process.stderr.write(
+        `[token-budget] ⚠  Project "${project}" (${priority}): ${Math.round(myPct * 100)}% of allocation` +
+        ` (${myUsed.toLocaleString()}/${Math.round(myBudget).toLocaleString()} tokens)\n`
+      );
+    }
+  }
+}
+
+main().catch(() => { /* never crash the hook */ });