therookie 0.4.3

package/templates/hook/lib/dispatcher.sh

@@ -0,0 +1,423 @@
+#!/bin/bash
+# Rookie hot-write dispatcher — batch-mutate POST 의 retry + partial failure 처리.
+# spec: docs/superpowers/specs/2026-04-23-post-v5-decisions.md §17.2 H-2.1 / H-2.2
+# plan: docs/superpowers/plans/2026-05-05-v6-p1-3-hot-write-resilience.md Task 1
+#
+# 함수:
+#   mutate_dispatch ENDPOINT TOKEN USER_ID SESSION_ID MUTATE_JSON
+#     return 0 = 성공 (partial failure 재큐 가능 포함)
+#     return 1 = 큐화 (전체 실패)
+#     return 2 = no-op (MUTATE_JSON 빈값)
+#
+# 의존:
+#   queue.sh : queue_enqueue (없으면 telemetry 로 fallback)
+#   curl     : --max-time 10 + http_code 회수 (flush-session.sh 패턴 동일)
+#   jq       : 응답 partial failure 파싱 (없으면 전체 재큐 + warn)
+#   node     : retry payload 재구성 (queue.sh 와 동일하게 node 의존 가정)
+#
+# 보안 (spec §10):
+#   - mutate_json 본문은 stdout 으로 출력 금지 (telemetry 로그도 본문 미포함, status/session 만)
+#   - 임시 파일은 mktemp + trap 으로 정리
+#   - 큐 디렉토리 권한 chmod 600 은 queue.sh 가 보장
+
+ROOKIE_DROP_LOG="${ROOKIE_DROP_LOG:-$HOME/.rookie/dropped-mutations.log}"
+# spec §17.2 H-2.3 dead-letter 격리 디렉토리 — queue.sh 의 ROOKIE_DEAD_LETTER_DIR 와 일관.
+ROOKIE_DEAD_LETTER_DIR="${ROOKIE_DEAD_LETTER_DIR:-$HOME/.rookie/dead-letter}"
+
+# drop log 디렉토리 보장 — stderr redirect 가 silent fail 하지 않도록.
+mkdir -p "$(dirname "$ROOKIE_DROP_LOG")" 2>/dev/null || true
+
+# 내부: 1회 POST.  $1=endpoint $2=token $3=user_id $4=mutate_json $5=output_body_path
+# stdout 으로 http_code 만 출력. curl exit ≠ 0 이면 "000".
+# curl stderr 는 ROOKIE_DROP_LOG 로 보존 — DNS/TLS/timeout 진단을 위해 silent 차단.
+_post_once() {
+  local endpoint="$1"
+  local token="$2"
+  local user_id="$3"
+  local mutate_json="$4"
+  local out_body="$5"
+  local code
+  # spec 2026-07-06 §F-1 — x-rookie-hostname 전송(세션 project 의 repo_path 매칭 요구).
+  #   dispatch 는 origin 호스트에서 실행되므로 $(hostname) == 세션 발생 호스트.
+  code=$(curl -sS --max-time 10 \
+    -X POST \
+    -H "Authorization: Bearer $token" \
+    -H "Content-Type: application/json" \
+    -H "x-rookie-user-id: $user_id" \
+    -H "x-rookie-hostname: $(hostname)" \
+    -d "$mutate_json" \
+    -o "$out_body" \
+    -w "%{http_code}" \
+    "$endpoint/api/rookie/batch-mutate" 2>>"$ROOKIE_DROP_LOG") || code="000"
+  if [ -z "$code" ]; then
+    code="000"
+  fi
+  printf '%s' "$code"
+}
+
+# 내부: failed 배열 + 원본 mutate_json 으로 retry payload 재구성.
+# stdout = retry_json (jq + node 둘 다 사용 가능 시), 실패 시 비어있음 → caller 가 fallback.
+# working_cards 는 object 이므로 failed.type=working_cards 가 한 건이라도 있으면 통째로 보존.
+# self_rules / evidence / verifications 는 array → failed.index 에 해당하는 element 만 추출.
+_build_retry_payload() {
+  local mutate_json="$1"
+  local failed_json="$2"
+  if ! command -v node >/dev/null 2>&1; then
+    return 1
+  fi
+  node -e "
+    try {
+      const src = JSON.parse(process.argv[1]);
+      const failed = JSON.parse(process.argv[2]);
+      if (!Array.isArray(failed) || failed.length === 0) { process.exit(1); }
+      const out = {};
+      const wcFail = failed.some(f => f && f.type === 'working_cards');
+      if (wcFail && src.working_cards && typeof src.working_cards === 'object') {
+        out.working_cards = src.working_cards;
+      }
+      for (const arrType of ['self_rules', 'evidence', 'verifications']) {
+        const idxs = failed
+          .filter(f => f && f.type === arrType && Number.isInteger(f.index))
+          .map(f => f.index);
+        if (idxs.length === 0) continue;
+        const arr = Array.isArray(src[arrType]) ? src[arrType] : [];
+        const picked = idxs
+          .filter(i => i >= 0 && i < arr.length)
+          .map(i => arr[i]);
+        if (picked.length > 0) out[arrType] = picked;
+      }
+      const keys = Object.keys(out);
+      if (keys.length === 0) { process.exit(1); }
+      // spec 2026-07-06 §F-1(a) — top-level repo 컨텍스트 보존(재시도 저장이 세션 project 를 잃지 않도록).
+      //   mutation key 유무 판정 이후에 부착 — repo 컨텍스트만으로 재큐되지 않게(empty-check 는 mutation 만).
+      if (typeof src.repo_url === 'string') out.repo_url = src.repo_url;
+      if (typeof src.repo_path === 'string') out.repo_path = src.repo_path;
+      process.stdout.write(JSON.stringify(out));
+    } catch (e) {
+      process.stderr.write('build_retry_payload_error: ' + (e && e.message ? e.message : String(e)) + '\n');
+      process.exit(1);
+    }
+  " "$mutate_json" "$failed_json" 2>>"$ROOKIE_DROP_LOG"
+}
+
+# 내부: failed paths 배열 + 원본 mutate_json 으로 결함 element 를 **제외**한 payload 재구성.
+# spec §17.2 H-2.3 — _build_retry_payload 와 대칭 (그 함수는 failed 만 추출, 본 함수는 failed 만 제외).
+# stdout = filtered_json (성공 시), 실패/empty 시 비어있음 → caller 가 fallback.
+_build_filtered_payload() {
+  local mutate_json="$1"
+  local failed_paths_json="$2"  # 예: [["verifications", 0, "fact_id"], ["self_rules", 1, "category"]]
+  if ! command -v node >/dev/null 2>&1; then
+    return 1
+  fi
+  node -e "
+    try {
+      const src = JSON.parse(process.argv[1]);
+      const paths = JSON.parse(process.argv[2]);
+      if (!Array.isArray(paths) || paths.length === 0) { process.exit(1); }
+      const failedIdxByType = {
+        working_cards: false,
+        self_rules: new Set(),
+        evidence: new Set(),
+        verifications: new Set(),
+      };
+      for (const p of paths) {
+        if (!Array.isArray(p) || p.length === 0) continue;
+        const t = p[0];
+        if (t === 'working_cards') { failedIdxByType.working_cards = true; continue; }
+        if (Object.prototype.hasOwnProperty.call(failedIdxByType, t) && Number.isInteger(p[1])) {
+          failedIdxByType[t].add(p[1]);
+        }
+      }
+      const out = {};
+      if (src.working_cards && !failedIdxByType.working_cards) out.working_cards = src.working_cards;
+      for (const arrType of ['self_rules', 'evidence', 'verifications']) {
+        const arr = Array.isArray(src[arrType]) ? src[arrType] : [];
+        if (arr.length === 0) continue;
+        const kept = arr.filter((_, i) => !failedIdxByType[arrType].has(i));
+        if (kept.length > 0) out[arrType] = kept;
+      }
+      const keys = Object.keys(out);
+      if (keys.length === 0) { process.exit(1); }
+      // spec 2026-07-06 §F-1(a) — top-level repo 컨텍스트 보존(400 재구성 저장도 세션 project 유지).
+      if (typeof src.repo_url === 'string') out.repo_url = src.repo_url;
+      if (typeof src.repo_path === 'string') out.repo_path = src.repo_path;
+      process.stdout.write(JSON.stringify(out));
+    } catch (e) {
+      process.stderr.write('build_filtered_payload_error: ' + (e && e.message ? e.message : String(e)) + '\n');
+      process.exit(1);
+    }
+  " "$mutate_json" "$failed_paths_json" 2>>"$ROOKIE_DROP_LOG"
+}
+
+# 내부: queue_enqueue wrapper.  queue.sh 가 source 안 됐으면 telemetry 로 fallback.
+_safe_enqueue() {
+  local label="$1"
+  local body="$2"
+  local code="$3"
+  if command -v queue_enqueue >/dev/null 2>&1; then
+    queue_enqueue "$label" "$body" "$code" 2>/dev/null
+    return $?
+  fi
+  printf '%s queue_unavailable label=%s code=%s\n' \
+    "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$label" "$code" \
+    >> "$ROOKIE_DROP_LOG" 2>/dev/null || true
+  return 1
+}
+
+# 내부: partial failure 처리. http_code=200 응답 body 를 파싱해 failed[] 분기.
+# 0 return = 처리 완료 (정상 또는 retry 재큐 성공/fallback)
+_handle_200() {
+  local body_path="$1"
+  local mutate_json="$2"
+  local session_id="$3"
+
+  # jq 미설치 → 응답 schema 파싱 불가능. 보수적 처리: 전체 mutate_json 을 retry 큐로 재적재
+  # + warn 1줄. silent drop 방지.
+  if ! command -v jq >/dev/null 2>&1; then
+    _safe_enqueue "$session_id-mutate-retry" "$mutate_json" "200-jq-missing" || true
+    printf '%s jq_missing_partial_failure_unknown session=%s\n' \
+      "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$session_id" \
+      >> "$ROOKIE_DROP_LOG" 2>/dev/null || true
+    return 0
+  fi
+
+  local failed_count jq_status
+  failed_count=$(jq -r '.summary.failed | length // 0' < "$body_path" 2>>"$ROOKIE_DROP_LOG")
+  jq_status=$?
+  if [ "$jq_status" -ne 0 ] || [ -z "$failed_count" ] || [ "$failed_count" = "null" ]; then
+    # jq 파싱 실패 — 응답 schema 비정상. silent 0 처리 금지, fallback 으로 전체 재큐.
+    _safe_enqueue "$session_id-mutate-retry" "$mutate_json" "200-jq-parse-fail" || true
+    printf '%s jq_parse_failed session=%s\n' \
+      "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$session_id" \
+      >> "$ROOKIE_DROP_LOG" 2>/dev/null || true
+    return 0
+  fi
+
+  if [ "$failed_count" -le 0 ] 2>/dev/null; then
+    return 0
+  fi
+
+  local failed_json
+  failed_json=$(jq -c '.summary.failed' < "$body_path" 2>>"$ROOKIE_DROP_LOG") || failed_json=""
+  if [ -z "$failed_json" ] || [ "$failed_json" = "null" ]; then
+    # failed length > 0 인데 추출 실패 — 비정상. fallback 으로 전체 재큐.
+    _safe_enqueue "$session_id-mutate-retry" "$mutate_json" "200-failed-extract-fail" || true
+    return 0
+  fi
+
+  local retry_json
+  retry_json=$(_build_retry_payload "$mutate_json" "$failed_json") || retry_json=""
+  if [ -z "$retry_json" ]; then
+    _safe_enqueue "$session_id-mutate-retry" "$mutate_json" "200-build-fail" || true
+    return 0
+  fi
+
+  _safe_enqueue "$session_id-mutate-retry" "$retry_json" "200-partial" || true
+  return 0
+}
+
+# 내부: HTTP 400 invalid_body 응답 처리 — spec §17.2 H-2.3.
+# stdout = 결함 element 를 제외한 재구성 mutate_json (재시도 가능, non-empty 일 때),
+# 빈 출력 = caller 가 fallback (전체 dead-letter or 기존 400 로직 진입).
+# return 0 = invalid_body 분기 처리됨, return 1 = invalid_body 아님/파싱 불가 → caller 가 기존 400 로직.
+_handle_400_invalid_body() {
+  local body_path="$1"
+  local mutate_json="$2"
+  local session_id="$3"
+
+  if ! command -v jq >/dev/null 2>&1; then
+    return 1
+  fi
+
+  local error_kind
+  error_kind=$(jq -r '.error // ""' < "$body_path" 2>>"$ROOKIE_DROP_LOG")
+  if [ "$error_kind" != "invalid_body" ]; then
+    return 1
+  fi
+
+  local paths_json
+  paths_json=$(jq -c '[.detail[]?.path]' < "$body_path" 2>>"$ROOKIE_DROP_LOG") || paths_json=""
+  if [ -z "$paths_json" ] || [ "$paths_json" = "null" ] || [ "$paths_json" = "[]" ]; then
+    return 1
+  fi
+
+  # 결함 element 들 dead-letter 이동 (전체 mutate_json 보존 — 추적용).
+  # spec §17.2 H-2.3: 재시도 무의미 → 즉시 격리. spec §10: chmod 600.
+  local ts
+  ts=$(date -u +%Y%m%dT%H%M%SZ)
+  local dead_letter_path="$ROOKIE_DEAD_LETTER_DIR/${session_id}-mutate-invalid-${ts}.jsonl"
+  mkdir -m 700 -p "$ROOKIE_DEAD_LETTER_DIR" 2>/dev/null || true
+  printf '%s\n' "$mutate_json" > "$dead_letter_path" 2>>"$ROOKIE_DROP_LOG"
+  chmod 600 "$dead_letter_path" 2>/dev/null || true
+  # telemetry: path 만 기록, 본문 미포함 (spec §10).
+  printf '%s invalid_body session=%s paths=%s dead_letter=%s\n' \
+    "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$session_id" "$paths_json" "$dead_letter_path" \
+    >> "$ROOKIE_DROP_LOG" 2>/dev/null || true
+
+  # 정상 element 재구성 — 모두 결함이면 빈 출력 (caller 가 fallback).
+  local filtered
+  filtered=$(_build_filtered_payload "$mutate_json" "$paths_json") || filtered=""
+  printf '%s' "$filtered"
+  return 0
+}
+
+mutate_dispatch() {
+  local endpoint="$1"
+  local token="$2"
+  local user_id="$3"
+  local session_id="$4"
+  local mutate_json="$5"
+  # spec §17.2 H-2.3: 재귀 cap=2. 외부 호출은 depth=0, _handle_400_invalid_body 회수 후 +1.
+  local depth="${6:-0}"
+
+  if [ -z "$mutate_json" ]; then
+    return 2
+  fi
+
+  local body_tmp
+  body_tmp=$(mktemp -t rookie-mutate-body.XXXXXX 2>>"$ROOKIE_DROP_LOG") || body_tmp=""
+  if [ -z "$body_tmp" ]; then
+    # mktemp 실패 시 silent drop 차단 — partial failure 회수 불가능하므로
+    # 1차 POST 시도조차 안 하고 mutate_json 전체를 재큐에 넣어 다음 drain 으로 회수.
+    # spec §17.2 H-2 큐 메커니즘 의존 (서버측 멱등성 + retry cap).
+    _safe_enqueue "$session_id-mutate" "$mutate_json" "mktemp-fail" || true
+    printf '%s mktemp_fail session=%s\n' \
+      "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$session_id" \
+      >> "$ROOKIE_DROP_LOG" 2>/dev/null || true
+    return 1
+  fi
+  # spec §10: 임시 파일에 응답 body 가 들어가지만 본문은 stdout 출력 금지.
+  # trap 으로 함수 종료 시 정리 (bash RETURN trap, dispatcher.sh shebang 보장).
+  # set -u 호환을 위해 :- 가드.
+  trap 'rm -f "${body_tmp:-}" 2>/dev/null || true' RETURN
+
+  local http_code
+  http_code=$(_post_once "$endpoint" "$token" "$user_id" "$mutate_json" "$body_tmp")
+
+  if [ "$http_code" = "200" ]; then
+    _handle_200 "$body_tmp" "$mutate_json" "$session_id"
+    return 0
+  fi
+
+  # spec §17.2 H-2.3 — 400 invalid_body partial validation 회수.
+  # depth<2 일 때만 회수 시도. 재구성 JSON 이 있으면 재귀 호출 (sleep/재큐 우회 — 결함 element 는 이미 dead-letter 격리됨).
+  # _handle_400_invalid_body 가 return 1 (invalid_body 아님 / jq 미설치 / 파싱 실패) → 기존 H-2.1 retry 로직 진입.
+  if [ "$http_code" = "400" ] && [ "$depth" -lt 2 ]; then
+    local refiltered
+    refiltered=$(_handle_400_invalid_body "$body_tmp" "$mutate_json" "$session_id")
+    local handle_status=$?
+    if [ "$handle_status" = "0" ]; then
+      if [ -n "$refiltered" ]; then
+        # 재구성 JSON 재시도 (depth+1)
+        mutate_dispatch "$endpoint" "$token" "$user_id" "$session_id" "$refiltered" "$((depth + 1))"
+        return $?
+      fi
+      # 모든 element 결함 → 이미 dead-letter 이동됨, 더 이상 할 일 없음.
+      return 0
+    fi
+    # handle_status=1 → invalid_body 분기 아님 → 아래 기존 retry 로직으로 fall-through
+  fi
+
+  # spec §17.2 H-2.3 무한 루프 방지: depth>=2 도달 했는데도 또 invalid_body → 통째 dead-letter.
+  # (재구성을 또 해봐도 같은 결함 클래스 — 재시도 무의미. 큐 재진입 차단.)
+  if [ "$http_code" = "400" ] && [ "$depth" -ge 2 ]; then
+    if command -v jq >/dev/null 2>&1; then
+      local error_kind_cap
+      error_kind_cap=$(jq -r '.error // ""' < "$body_tmp" 2>>"$ROOKIE_DROP_LOG")
+      if [ "$error_kind_cap" = "invalid_body" ]; then
+        local ts_cap
+        ts_cap=$(date -u +%Y%m%dT%H%M%SZ)
+        local dead_letter_path_cap="$ROOKIE_DEAD_LETTER_DIR/${session_id}-mutate-invalid-cap-${ts_cap}.jsonl"
+        mkdir -m 700 -p "$ROOKIE_DEAD_LETTER_DIR" 2>/dev/null || true
+        printf '%s\n' "$mutate_json" > "$dead_letter_path_cap" 2>>"$ROOKIE_DROP_LOG"
+        chmod 600 "$dead_letter_path_cap" 2>/dev/null || true
+        printf '%s invalid_body_cap session=%s depth=%s dead_letter=%s\n' \
+          "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$session_id" "$depth" "$dead_letter_path_cap" \
+          >> "$ROOKIE_DROP_LOG" 2>/dev/null || true
+        return 1
+      fi
+    fi
+    # invalid_body 아닌 400 (또는 jq 미설치) → fall-through 으로 기존 H-2.1 retry 로직 진입.
+  fi
+
+  # 1차 실패 → spec §17.2 H-2.1 sleep 1 + 1회 retry.
+  sleep 1
+  http_code=$(_post_once "$endpoint" "$token" "$user_id" "$mutate_json" "$body_tmp")
+
+  if [ "$http_code" = "200" ]; then
+    _handle_200 "$body_tmp" "$mutate_json" "$session_id"
+    return 0
+  fi
+
+  # 2회 모두 실패 → 전체 재큐.
+  _safe_enqueue "$session_id-mutate" "$mutate_json" "$http_code" || true
+  return 1
+}
+
+# v6 P1 #5 — Stage 1 측정 hook buffer flush.
+# spec §7.1 / plan Task 4
+#
+# PreToolUse hook 가 적재한 ~/.rookie/metric-pending/<session>-md-read.jsonl 을
+# entries 배열로 wrap → /api/rookie/metric/md-read 로 batch POST.
+# 200 → buffer 삭제. 실패 → buffer 보존 (다음 세션 재시도, retry cap 안 둠).
+#
+# return 0 = 성공 또는 no-op (buffer 없음/빈값), 1 = POST 실패 (buffer 잔존)
+metric_dispatch_md_read() {
+  local endpoint="$1"
+  local token="$2"
+  local user_id="$3"
+  local session_id="$4"
+  local buf_dir="${ROOKIE_METRIC_BUFFER_DIR:-$HOME/.rookie/metric-pending}"
+  local buf_file="$buf_dir/${session_id}-md-read.jsonl"
+
+  [ -f "$buf_file" ] || return 0
+  if [ ! -s "$buf_file" ]; then
+    rm -f "$buf_file"
+    return 0
+  fi
+
+  if ! command -v node >/dev/null 2>&1; then
+    return 1
+  fi
+
+  local body
+  body=$(node -e "
+    try {
+      const fs = require('fs');
+      const lines = fs.readFileSync(process.argv[1], 'utf8').split('\n').filter(Boolean);
+      const entries = [];
+      for (const line of lines) {
+        try { entries.push(JSON.parse(line)); } catch {}
+      }
+      if (entries.length === 0) process.exit(1);
+      process.stdout.write(JSON.stringify({ entries }));
+    } catch (e) {
+      process.stderr.write('metric_buffer_parse_error: ' + (e && e.message ? e.message : String(e)) + '\n');
+      process.exit(1);
+    }
+  " "$buf_file" 2>>"$ROOKIE_DROP_LOG") || return 1
+
+  if [ -z "$body" ]; then
+    return 1
+  fi
+
+  local code
+  code=$(curl -sS --max-time 10 -o /dev/null -w "%{http_code}" \
+    -X POST \
+    -H "Authorization: Bearer $token" \
+    -H "Content-Type: application/json" \
+    -H "x-rookie-user-id: $user_id" \
+    -d "$body" \
+    "$endpoint/api/rookie/metric/md-read" 2>>"$ROOKIE_DROP_LOG") || code="000"
+
+  if [ "$code" = "200" ]; then
+    rm -f "$buf_file"
+    return 0
+  fi
+
+  # 실패 — buffer 보존, telemetry 1줄.
+  printf '%s metric_md_read_post_failed session=%s code=%s\n' \
+    "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$session_id" "$code" \
+    >> "$ROOKIE_DROP_LOG" 2>/dev/null || true
+  return 1
+}