@trycore/spec-build-harness 0.8.5 → 0.11.0

package/hooks/build/lib/agent-context.sh

@@ -0,0 +1,139 @@
+#!/usr/bin/env bash
+# agent-context.sh — hidratación de la caché de proyección desde GET /agent/context
+# [EP-OR-08-B]. Es la ÚNICA pieza que conoce la forma cruda de la respuesta del servidor:
+# la normaliza al esquema documentado del plan (fetched_at/project/active_slice/nudges/
+# context/lease) para que guards, renders y nudges dependan solo de ese esquema. Si el
+# servidor añade o renombra campos, se toca este fichero y nada más.
+# Diseño fail-open: ante red caída o respuesta ilegible, la caché ANTERIOR queda intacta.
+
+source "$(dirname "${BASH_SOURCE[0]}")/runtime-client.sh"
+
+AGENT_CONTEXT_PATH="/agent/context"
+
+# agent_context_normalize <fichero-con-el-json-crudo> — imprime el JSON normalizado
+# (o "{}" si es ilegible, con rc 1). El crudo se pasa por FICHERO, no por argv: la
+# respuesta puede traer nudges y wiring largos y argv está acotado por ARG_MAX.
+agent_context_normalize() {
+  local raw_file="$1"
+  local out rc
+  command -v python3 >/dev/null 2>&1 || { echo "{}"; return 1; }
+  # La salida de python3 se captura en vez de dejarla fluir directo a stdout:
+  # si el script ya imprimió "{}" y salió con rc 1 (JSON ilegible), no queremos
+  # que el manejo de fallo de abajo imprima un segundo "{}" encima (doble salida).
+  out="$(python3 - "$raw_file" <<'PY' 2>/dev/null
+import json,sys,datetime
+
+def as_dict(x):
+    return x if isinstance(x, dict) else {}
+
+def as_list(x):
+    return x if isinstance(x, list) else []
+
+def first(*vals):
+    for v in vals:
+        if v is not None:
+            return v
+    return None
+
+try:
+    raw = as_dict(json.load(open(sys.argv[1])))
+except Exception:
+    print("{}")
+    sys.exit(1)
+
+proj = as_dict(first(raw.get("project"), raw.get("project_facts"), {}))
+scaffold = as_dict(proj.get("scaffold"))
+ds = as_dict(proj.get("design_source"))
+sl = as_dict(first(raw.get("active_slice"), raw.get("slice"), {}))
+
+wiring = []
+for w in as_list(first(sl.get("wiring_checklist"), sl.get("wiring"), sl.get("wiring_failing"), [])):
+    w = as_dict(w)
+    # Sin `status` se asume failing: la lista `wiring_failing` del servidor ya viene filtrada.
+    if w.get("status") in (None, "failing"):
+        wiring.append({"item_id": first(w.get("item_id"), w.get("id")), "kind": w.get("kind")})
+
+subs = []
+for s in as_list(sl.get("sub_slices")):
+    s = as_dict(s)
+    if s.get("status") != "done":
+        sid = first(s.get("id"), s.get("sub_slice_id"))
+        if sid:
+            subs.append(sid)
+
+nudges = []
+for n in as_list(raw.get("nudges")):
+    if isinstance(n, str):
+        nudges.append({"kind": "info", "message": n})
+    else:
+        n = as_dict(n)
+        nudges.append({"kind": first(n.get("kind"), n.get("type"), "info"),
+                       "message": first(n.get("message"), n.get("text"), "")})
+
+hus = [h for h in as_list(first(sl.get("stories"), sl.get("hus"), [])) if isinstance(h, str)]
+ctx = as_dict(raw.get("context"))
+lease = as_dict(raw.get("lease"))
+checkpoint = as_dict(sl.get("checkpoint")) or None
+
+out = {
+    "fetched_at": datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+    "source": "agent_context",
+    "project": {
+        "scaffold_confirmed": bool(first(proj.get("scaffold_confirmed"), scaffold.get("confirmed"), False)),
+        "design_source_applies": bool(first(proj.get("design_source_applies"), ds.get("applies"), False)),
+        "design_source_confirmed": bool(first(proj.get("design_source_confirmed"), ds.get("confirmed"), False)),
+        "project_kind": first(proj.get("project_kind"), raw.get("project_kind")),
+        "harness_phase": first(proj.get("harness_phase"), raw.get("harness_phase")),
+        "foundation_done": bool(first(proj.get("foundation_done"), as_dict(proj.get("foundation")).get("done"), False)),
+    },
+    "active_slice": None if not sl else {
+        "slice_id": first(sl.get("slice_id"), sl.get("id")),
+        "epic_code": first(sl.get("epic_code"), sl.get("epica")),
+        "epic_title": sl.get("epic_title"),
+        "hus": hus,
+        "phase": sl.get("phase"),
+        "gates": as_dict(sl.get("gates")),
+        "branch": first(sl.get("branch"), sl.get("branch_base")),
+        "openspec_change": sl.get("openspec_change"),
+        "docs_ref": sl.get("docs_ref"),
+        "wiring_failing": wiring,
+        "sub_slices_pending": subs,
+        "resume_hint": first(sl.get("resume_hint"), as_dict(sl.get("session_continuity")).get("resume_hint")),
+        "checkpoint": checkpoint,
+    },
+    "nudges": nudges,
+    "context": {"manifest_hash": first(ctx.get("manifest_hash"), raw.get("manifest_hash")),
+                "version": first(ctx.get("version"), raw.get("context_version"))},
+    "lease": {"expires_at": first(lease.get("expires_at"), raw.get("lease_expires_at")),
+              "ttl_s": first(lease.get("ttl_s"), raw.get("lease_ttl_s"))},
+}
+print(json.dumps(out, ensure_ascii=False))
+PY
+)"
+  rc=$?
+  if [ $rc -ne 0 ]; then
+    echo "{}"
+    return 1
+  fi
+  printf '%s\n' "$out"
+  return 0
+}
+
+# agent_context_fetch_and_cache — GET /agent/context, normaliza y escribe la caché.
+# rc 0 = caché actualizada · 1 = no se pudo (red, status != 200, respuesta ilegible):
+# en ese caso la caché anterior NO se toca, y los guards siguen operando con ella.
+agent_context_fetch_and_cache() {
+  local body status tmp norm rc
+  body="$(runtime_get "$AGENT_CONTEXT_PATH")"
+  status="$(runtime_http_status)"
+  [ "$status" = "200" ] || return 1
+  tmp="$(mktemp)" || return 1
+  printf '%s' "$body" > "$tmp"
+  norm="$(agent_context_normalize "$tmp")"
+  rc=$?
+  rm -f "$tmp"
+  [ $rc -eq 0 ] || return 1
+  [ -n "$norm" ] && [ "$norm" != "{}" ] || return 1
+  runtime_projection_write "$norm" || return 1
+  return 0
+}

package/hooks/build/lib/config.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# config.sh — helpers de lectura de config/build-config.json. Extraído de state-io.sh
+# [EP-OR-08-A] para que sea infraestructura común a legacy/dual/runtime: retirar
+# state-io.sh en modo runtime puro no debe romper context-monitor, que solo necesita
+# config_get. Diseño: fail-open, igual que state-io.sh — nunca lanza.
+
+# config_root — raíz del proyecto consumidor (misma señal que state_path en state-io.sh).
+config_root() {
+  echo "${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+}
+
+# config_get <clave.punteada> <default>
+config_get() {
+  local key="$1" def="$2" file
+  file="${BUILD_CONFIG_FILE:-$(config_root)/.claude/config/build-config.json}"
+  command -v python3 >/dev/null 2>&1 || { echo "$def"; return; }
+  python3 - "$file" "$key" "$def" <<'PY' 2>/dev/null || echo "$def"
+import json,sys
+file,key,default=sys.argv[1],sys.argv[2],sys.argv[3]
+try:
+    d=json.load(open(file))
+    for part in key.split("."): d=d[part]
+    print(d if not isinstance(d,bool) else str(d).lower())
+except Exception:
+    print(default)
+PY
+}

package/hooks/build/lib/projection.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+# projection.sh — lectores de la caché de proyección local [EP-OR-08-B].
+# La caché la ESCRIBE session-start.sh (vía lib/agent-context.sh) desde GET /agent/context;
+# aquí solo se LEE: ninguna función de este fichero toca la red, y de esa garantía dependen
+# los cuatro guards de PreToolUse (spec §4.2-B: «PreToolUse: prohibida la red»).
+# Diseño fail-open, igual que config.sh/state-io.sh: sin caché, sin python3 o con JSON
+# corrupto se devuelve el default y jamás se lanza.
+
+source "$(dirname "${BASH_SOURCE[0]}")/runtime-client.sh"
+
+# projection_get <clave.punteada> <default>
+# Escalares tal cual; booleanos en minúsculas (true/false, comparables desde bash);
+# dict/list como JSON compacto para encadenar con python3 en el llamador.
+projection_get() {
+  local key="$1" def="$2" file
+  file="$(runtime_projection_path)"
+  [ -f "$file" ] || { echo "$def"; return; }
+  command -v python3 >/dev/null 2>&1 || { echo "$def"; return; }
+  python3 - "$file" "$key" "$def" <<'PY' 2>/dev/null || echo "$def"
+import json,sys
+path,key,default=sys.argv[1],sys.argv[2],sys.argv[3]
+try:
+    d=json.load(open(path))
+    for part in key.split("."):
+        if isinstance(d,dict) and part in d:
+            d=d[part]
+        else:
+            raise KeyError(part)
+    if d is None:
+        print(default)
+    elif isinstance(d,bool):
+        print(str(d).lower())
+    elif isinstance(d,(dict,list)):
+        print(json.dumps(d,ensure_ascii=False))
+    else:
+        print(d)
+except Exception:
+    print(default)
+PY
+}
+
+# projection_age_seconds — segundos desde `fetched_at`. 999999 si no hay caché, no hay
+# python3 o la fecha es ilegible (equivale a «infinitamente vieja»: el llamador avisará
+# de stale en vez de fingir frescura).
+projection_age_seconds() {
+  local file; file="$(runtime_projection_path)"
+  [ -f "$file" ] || { echo 999999; return; }
+  command -v python3 >/dev/null 2>&1 || { echo 999999; return; }
+  python3 - "$file" <<'PY' 2>/dev/null || echo 999999
+import json,sys,datetime
+try:
+    d=json.load(open(sys.argv[1]))
+    t=datetime.datetime.strptime(d.get("fetched_at") or "","%Y-%m-%dT%H:%M:%SZ")
+    t=t.replace(tzinfo=datetime.timezone.utc)
+    now=datetime.datetime.now(datetime.timezone.utc)
+    print(max(0,int((now-t).total_seconds())))
+except Exception:
+    print(999999)
+PY
+}
+
+# projection_is_stale — rc 0 si la caché supera runtime.stale_seconds (default 900 s).
+# rc, no stdout: se usa como condición (`if projection_is_stale; then …`).
+projection_is_stale() {
+  local age max
+  age="$(projection_age_seconds)"
+  max="$(config_get runtime.stale_seconds 900)"
+  case "$max" in ''|*[!0-9]*) max=900 ;; esac
+  case "$age" in ''|*[!0-9]*) age=999999 ;; esac
+  [ "$age" -gt "$max" ]
+}