@kenkaiiii/ggcoder-eyes 0.1.0

package/probes/capture_email/impl/mailpit.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# impl: mailpit
+# Talk to the running Mailpit HTTP API. Works for any app that can be pointed
+# at a local SMTP server — language-agnostic.
+#
+# Usage:
+#   mail.sh count                     — number of captured messages
+#   mail.sh list [--limit N]          — JSON summary of recent messages
+#   mail.sh latest                    — subject + from/to + redacted body of most recent
+#   mail.sh read <id>                 — full (redacted) body of message by ID
+#   mail.sh clear                     — delete all captured messages
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/_lib.sh"
+
+PORT="$(eyes_state_get mailpit.http_port)"
+[ -n "$PORT" ] || eyes_die "mailpit not installed; run capture_email install"
+BASE="http://127.0.0.1:$PORT"
+curl -sf "$BASE/api/v1/info" >/dev/null 2>&1 || eyes_die "mailpit not responding at $BASE"
+
+CMD="${1:-}"
+shift || true
+
+case "$CMD" in
+  count)
+    curl -sf "$BASE/api/v1/messages?limit=1" | python3 -c 'import sys,json; print(json.load(sys.stdin).get("total",0))'
+    ;;
+  list)
+    LIMIT=20
+    [ "${1:-}" = "--limit" ] && LIMIT="$2"
+    curl -sf "$BASE/api/v1/messages?limit=$LIMIT" | python3 -c '
+import sys, json
+d = json.load(sys.stdin)
+for m in d.get("messages", []):
+    print(json.dumps({"id": m["ID"], "from": m["From"]["Address"], "to": [t["Address"] for t in m.get("To",[])], "subject": m["Subject"], "created": m["Created"]}))
+' | "$SCRIPT_DIR/_redact.sh"
+    ;;
+  latest)
+    ID="$(curl -sf "$BASE/api/v1/messages?limit=1" | python3 -c 'import sys,json; d=json.load(sys.stdin); print(d["messages"][0]["ID"]) if d.get("messages") else None')"
+    [ -n "$ID" ] && [ "$ID" != "None" ] || eyes_die "no messages"
+    curl -sf "$BASE/api/v1/message/$ID" | python3 -c '
+import sys, json
+m = json.load(sys.stdin)
+print("id:", m["ID"])
+print("from:", m["From"]["Address"])
+print("to:", ", ".join(t["Address"] for t in m.get("To",[])))
+print("subject:", m["Subject"])
+print("---")
+print(m.get("Text") or m.get("HTML") or "")
+' | "$SCRIPT_DIR/_redact.sh"
+    ;;
+  read)
+    ID="${1:-}"
+    [ -n "$ID" ] || eyes_die "usage: mail.sh read <id>"
+    curl -sf "$BASE/api/v1/message/$ID" | python3 -c '
+import sys, json
+m = json.load(sys.stdin)
+print("id:", m["ID"])
+print("from:", m["From"]["Address"])
+print("subject:", m["Subject"])
+print("---")
+print(m.get("Text") or m.get("HTML") or "")
+' | "$SCRIPT_DIR/_redact.sh"
+    ;;
+  clear)
+    curl -sf -X DELETE "$BASE/api/v1/messages" >/dev/null
+    echo "cleared"
+    ;;
+  ""|help|-h|--help)
+    cat <<USAGE
+mail.sh <count|list|latest|read <id>|clear>
+USAGE
+    ;;
+  *)
+    eyes_die "unknown subcommand: $CMD"
+    ;;
+esac

package/probes/capture_email/install.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# capture_email/install.sh [impl]
+# Installs Mailpit — a local SMTP sink + HTTP UI that any app can point at
+# (Node/Python/Ruby/Go/Java/PHP/.NET — anything speaking SMTP works).
+#
+# After install you must configure your app's SMTP settings:
+#   host=127.0.0.1  port=<smtp_port>  user=""  pass=""  tls=off
+# Ports are written to .gg/eyes/state/mailpit.smtp_port and .gg/eyes/state/mailpit.http_port.
+set -euo pipefail
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$HERE/../../shared/_lib.sh"
+
+IMPL="${1:-mailpit}"
+[ "$IMPL" = "mailpit" ] || eyes_die "only 'mailpit' impl is provided"
+
+# Resolve or install binary into .gg/eyes/bin/mailpit
+BIN="$(eyes_bin_dir)/mailpit"
+if [ ! -x "$BIN" ]; then
+  if command -v mailpit >/dev/null 2>&1; then
+    ln -sf "$(command -v mailpit)" "$BIN"
+  elif [ "$(eyes_os)" = "darwin" ] && command -v brew >/dev/null 2>&1; then
+    brew install mailpit >&2 || eyes_die "brew install mailpit failed"
+    ln -sf "$(command -v mailpit)" "$BIN"
+  else
+    # Download a release binary from github
+    OS="$(eyes_os)"; ARCH="$(eyes_arch)"
+    case "$OS-$ARCH" in
+      darwin-amd64|darwin-arm64|linux-amd64|linux-arm64) : ;;
+      *) eyes_die "no prebuilt mailpit for $OS-$ARCH; install manually and re-run";;
+    esac
+    URL="https://github.com/axllent/mailpit/releases/latest/download/mailpit-${OS}-${ARCH}.tar.gz"
+    TMP="$(mktemp -d)"; trap 'rm -rf "$TMP"' EXIT
+    echo "downloading mailpit ($OS-$ARCH)..." >&2
+    eyes_timeout 60 curl -sSL -o "$TMP/mp.tgz" "$URL" || eyes_die "download failed: $URL"
+    tar -xzf "$TMP/mp.tgz" -C "$TMP" || eyes_die "extract failed"
+    cp "$TMP/mailpit" "$BIN"
+    chmod +x "$BIN"
+  fi
+fi
+
+# Allocate ports if not already allocated, then (re)start
+SMTP_PORT="$(eyes_state_get mailpit.smtp_port)"
+HTTP_PORT="$(eyes_state_get mailpit.http_port)"
+[ -n "$SMTP_PORT" ] || SMTP_PORT="$(eyes_free_port)"
+[ -n "$HTTP_PORT" ] || HTTP_PORT="$(eyes_free_port)"
+eyes_state_set mailpit.smtp_port "$SMTP_PORT"
+eyes_state_set mailpit.http_port "$HTTP_PORT"
+
+# Stop any prior instance
+OLD_PID="$(eyes_state_get mailpit.pid)"
+if [ -n "$OLD_PID" ] && kill -0 "$OLD_PID" 2>/dev/null; then
+  kill -TERM "$OLD_PID" 2>/dev/null || true
+  sleep 0.3
+fi
+
+LOG="$(eyes_out_dir)/mailpit.log"
+nohup "$BIN" --smtp "127.0.0.1:$SMTP_PORT" --listen "127.0.0.1:$HTTP_PORT" --quiet >"$LOG" 2>&1 &
+NEW_PID=$!
+eyes_state_set mailpit.pid "$NEW_PID"
+
+# Wait for HTTP port
+for _ in 1 2 3 4 5 6 7 8 9 10; do
+  curl -sf "http://127.0.0.1:$HTTP_PORT/api/v1/info" >/dev/null 2>&1 && break
+  sleep 0.3
+done
+curl -sf "http://127.0.0.1:$HTTP_PORT/api/v1/info" >/dev/null 2>&1 \
+  || eyes_die "mailpit did not come up; see $LOG"
+
+# Install the probe script
+DEST="$(eyes_root)/mail.sh"
+cp "$HERE/impl/mailpit.sh" "$DEST"
+chmod +x "$DEST"
+cp "$HERE/../../shared/_lib.sh" "$(eyes_root)/_lib.sh"
+cp "$HERE/../../shared/_redact.sh" "$(eyes_root)/_redact.sh"
+chmod +x "$(eyes_root)/_redact.sh"
+
+cat >&2 <<EOF
+mailpit running:
+  SMTP: 127.0.0.1:$SMTP_PORT    (point your app here)
+  HTTP: http://127.0.0.1:$HTTP_PORT
+  PID:  $NEW_PID
+  probe: $DEST  (subcommands: list, count, latest, read <id>, clear)
+EOF

package/probes/capture_email/test.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# test.sh — send a real message via SMTP to the running mailpit, then verify
+# the probe can list/read it.
+set -euo pipefail
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$HERE/../../shared/_lib.sh"
+
+PROBE="$(eyes_root)/mail.sh"
+[ -x "$PROBE" ] || eyes_die "probe not installed"
+
+SMTP_PORT="$(eyes_state_get mailpit.smtp_port)"
+HTTP_PORT="$(eyes_state_get mailpit.http_port)"
+[ -n "$SMTP_PORT" ] && [ -n "$HTTP_PORT" ] || eyes_die "mailpit state missing; re-run install"
+
+curl -sf "http://127.0.0.1:$HTTP_PORT/api/v1/info" >/dev/null \
+  || eyes_die "mailpit not responding; run install.sh"
+
+# Clear any prior messages
+"$PROBE" clear >/dev/null
+
+# Send via python smtplib (universal, no extra deps)
+eyes_require python3
+python3 - <<PY
+import smtplib
+from email.message import EmailMessage
+m = EmailMessage()
+m["Subject"] = "eyes-test"
+m["From"] = "probe@eyes.test"
+m["To"] = "user@eyes.test"
+m.set_content("hello from the eyes probe self-test. reset link: https://example.com/reset?token=sk-proj-secretxxxxxxxxxxxxx")
+with smtplib.SMTP("127.0.0.1", $SMTP_PORT, timeout=5) as s:
+    s.send_message(m)
+PY
+
+# Verify probe sees it
+COUNT="$("$PROBE" count)"
+[ "$COUNT" -ge 1 ] || eyes_die "expected >=1 message, got $COUNT"
+
+LATEST="$("$PROBE" latest)"
+echo "$LATEST" | grep -q 'eyes-test' || eyes_die "latest did not include our subject: $LATEST"
+echo "$LATEST" | grep -q 'REDACTED_OPENAI' || eyes_die "redactor did not scrub the fake token in the email body"
+
+echo "ok"

package/probes/http/impl/curl.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# impl: curl
+# Universal HTTP probe. Works for any backend/API regardless of language —
+# Express, FastAPI, Rails, Spring, Gin, Actix, Phoenix, Laravel, etc.
+#
+# Usage:
+#   http.sh <url> [method] [body-or-@file] [-H "Header: value" ...]
+#
+# Prints JSON to stdout: {"status":200,"size":1234,"headers":"<path>","body":"<path>","time_ms":45}
+# Body is redacted before writing.
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/_lib.sh"
+
+URL="${1:-}"
+[ -z "$URL" ] && eyes_die "usage: http.sh <url> [method] [body-or-@file] [-H ...]"
+METHOD="${2:-GET}"
+BODY="${3:-}"
+
+EXTRA_HEADERS=()
+if [ "$#" -gt 3 ]; then
+  shift 3
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      -H) EXTRA_HEADERS+=(-H "$2"); shift 2;;
+      *) eyes_die "unknown arg: $1";;
+    esac
+  done
+fi
+
+eyes_require curl
+
+TS="$(eyes_timestamp)"
+HEADERS="$(eyes_out_dir)/http-$TS.headers"
+BODY_OUT="$(eyes_out_dir)/http-$TS.body"
+
+# Build curl args
+ARGS=(-sS -D "$HEADERS" -o - -X "$METHOD" --max-time 20)
+ARGS+=("${EXTRA_HEADERS[@]}")
+if [ -n "$BODY" ]; then
+  case "$BODY" in
+    @*) ARGS+=(--data-binary "$BODY");;
+    *)  ARGS+=(-H "Content-Type: application/json" --data-binary "$BODY");;
+  esac
+fi
+
+START_MS=$(python3 -c 'import time; print(int(time.time()*1000))' 2>/dev/null || date +%s%3N 2>/dev/null || echo 0)
+
+# Pipe body through redactor, then measure size after redaction.
+if ! curl "${ARGS[@]}" "$URL" | "$(eyes_root)/_redact.sh" > "$BODY_OUT"; then
+  eyes_die "curl failed to reach $URL"
+fi
+END_MS=$(python3 -c 'import time; print(int(time.time()*1000))' 2>/dev/null || date +%s%3N 2>/dev/null || echo 0)
+
+STATUS="$(grep -m1 -oE 'HTTP/[0-9.]+ [0-9]+' "$HEADERS" | awk '{print $2}' || echo 0)"
+SIZE=$(wc -c < "$BODY_OUT" | awk '{print $1}')
+TIME_MS=$(( END_MS - START_MS ))
+
+# Also redact headers file in place (authorization, cookie)
+tmp="$(mktemp)"
+"$(eyes_root)/_redact.sh" < "$HEADERS" > "$tmp" && mv "$tmp" "$HEADERS"
+
+printf '{"status":%s,"size":%s,"time_ms":%s,"headers":"%s","body":"%s"}\n' \
+  "${STATUS:-0}" "$SIZE" "$TIME_MS" "$HEADERS" "$BODY_OUT"

package/probes/http/install.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# http/install.sh [impl]
+# Only one impl (curl). Copies it into .gg/eyes/http.sh.
+set -euo pipefail
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$HERE/../../shared/_lib.sh"
+
+IMPL="${1:-curl}"
+[ "$IMPL" = "curl" ] || eyes_die "only 'curl' impl exists for http"
+eyes_require curl
+
+DEST="$(eyes_root)/http.sh"
+cp "$HERE/impl/curl.sh" "$DEST"
+chmod +x "$DEST"
+cp "$HERE/../../shared/_lib.sh" "$(eyes_root)/_lib.sh"
+cp "$HERE/../../shared/_redact.sh" "$(eyes_root)/_redact.sh"
+chmod +x "$(eyes_root)/_redact.sh"
+
+echo "installed: $DEST (impl=curl)" >&2

package/probes/http/test.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# http/test.sh
+# Spin up a minimal local server, hit it with the probe, verify JSON output
+# describes the response.
+set -euo pipefail
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$HERE/../../shared/_lib.sh"
+
+PROBE="$(eyes_root)/http.sh"
+[ -x "$PROBE" ] || eyes_die "probe not installed: $PROBE"
+
+eyes_require python3
+PORT="$(eyes_free_port)"
+python3 -c "
+import http.server, socketserver, json, threading
+class H(http.server.BaseHTTPRequestHandler):
+    def do_GET(self):
+        self.send_response(200); self.send_header('content-type','application/json'); self.end_headers()
+        self.wfile.write(b'{\"ok\":true,\"token\":\"sk-proj-test-secret-xyz-1234567890\"}')
+    def log_message(self, *a): pass
+s = socketserver.TCPServer(('127.0.0.1', $PORT), H); threading.Thread(target=s.serve_forever, daemon=True).start()
+import time; time.sleep(30)
+" &
+SRV_PID=$!
+trap 'kill "$SRV_PID" 2>/dev/null || true' EXIT
+
+for _ in 1 2 3 4 5 6 7 8 9 10; do
+  curl -sf "http://127.0.0.1:$PORT/" >/dev/null 2>&1 && break
+  sleep 0.3
+done
+
+OUT_JSON="$("$PROBE" "http://127.0.0.1:$PORT/health")"
+echo "$OUT_JSON" | grep -q '"status":200' || eyes_die "expected status 200, got: $OUT_JSON"
+
+# Validate redactor ran on body
+BODY_PATH="$(echo "$OUT_JSON" | python3 -c 'import sys,json; print(json.load(sys.stdin)["body"])')"
+grep -q 'REDACTED_OPENAI' "$BODY_PATH" || eyes_die "redactor did not scrub the fake sk- token in body: $BODY_PATH"
+
+echo "ok: $OUT_JSON"

package/probes/runtime_logs/detect.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# Emits: {"candidates":["tail","adb-logcat","simctl","docker"], "primary":"..."}
+# tail works anywhere (you give it a log path); per-platform impls layer on top.
+set -euo pipefail
+ROOT="${EYES_PROJECT_ROOT:-$PWD}"
+CANDIDATES=()
+add() { case " ${CANDIDATES[*]:-} " in *" $1 "*) return;; esac; CANDIDATES+=("$1"); }
+
+# Android
+if [ -d "$ROOT/android" ] \
+   || [ -f "$ROOT/AndroidManifest.xml" ] \
+   || find "$ROOT" -maxdepth 3 -name "AndroidManifest.xml" 2>/dev/null | head -1 | grep -q .; then
+  add adb-logcat
+fi
+# iOS
+if [ -d "$ROOT/ios" ] \
+   || find "$ROOT" -maxdepth 2 -name "*.xcodeproj" 2>/dev/null | head -1 | grep -q . \
+   || [ -f "$ROOT/Podfile" ]; then
+  add simctl
+fi
+# Docker / compose
+if [ -f "$ROOT/docker-compose.yml" ] \
+   || [ -f "$ROOT/docker-compose.yaml" ] \
+   || [ -f "$ROOT/compose.yml" ] \
+   || [ -f "$ROOT/Dockerfile" ]; then
+  add docker
+fi
+# Everything can use tail; include it as the catch-all last so it's not primary.
+add tail
+
+printf '{"candidates":['
+first=1
+for c in "${CANDIDATES[@]}"; do
+  [ $first -eq 0 ] && printf ','
+  printf '"%s"' "$c"
+  first=0
+done
+printf '],"primary":"%s"}\n' "${CANDIDATES[0]}"

package/probes/runtime_logs/impl/adb-logcat.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# impl: adb-logcat
+# Android runtime logs. Works for native, RN, Flutter, Capacitor.
+#
+# Usage:
+#   logs-android.sh [--device <serial>] [--tag <tag>] [--lines N] [--grep <pattern>] [--level V|D|I|W|E|F]
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/_lib.sh"
+
+eyes_require adb
+
+DEVICE=""
+TAG=""
+LINES=200
+PATTERN=""
+LEVEL="V"
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --device) DEVICE="$2"; shift 2;;
+    --tag) TAG="$2"; shift 2;;
+    --lines) LINES="$2"; shift 2;;
+    --grep) PATTERN="$2"; shift 2;;
+    --level) LEVEL="$2"; shift 2;;
+    *) eyes_die "unknown arg: $1";;
+  esac
+done
+
+DEV_ARGS=()
+[ -n "$DEVICE" ] && DEV_ARGS+=(-s "$DEVICE")
+
+adb "${DEV_ARGS[@]}" get-state >/dev/null 2>&1 || eyes_die "no android device/emulator connected"
+
+FILTER=""
+if [ -n "$TAG" ]; then
+  FILTER="$TAG:$LEVEL *:S"
+fi
+
+# -d = dump and exit, -t N = last N lines
+OUT="$(eyes_timeout 10 adb "${DEV_ARGS[@]}" logcat -d -t "$LINES" $FILTER 2>/dev/null || true)"
+if [ -n "$PATTERN" ]; then
+  echo "$OUT" | grep -E "$PATTERN" | eyes_redact || true
+else
+  echo "$OUT" | eyes_redact
+fi

package/probes/runtime_logs/impl/docker.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# impl: docker
+# Tail a docker container's logs. Works for any language (the container is just a
+# PID from docker's PoV).
+#
+# Usage:
+#   logs-docker.sh <container-name-or-id> [--lines N] [--since <duration>] [--grep <pattern>] [--follow --timeout S]
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/_lib.sh"
+
+eyes_require docker
+
+CONTAINER="${1:-}"
+[ -z "$CONTAINER" ] && eyes_die "usage: logs-docker.sh <container> [--lines N] [--since 5m] [--grep p] [--follow --timeout S]"
+shift
+
+LINES=200
+SINCE=""
+PATTERN=""
+FOLLOW=0
+FTIMEOUT=5
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --lines) LINES="$2"; shift 2;;
+    --since) SINCE="--since $2"; shift 2;;
+    --grep) PATTERN="$2"; shift 2;;
+    --follow) FOLLOW=1; shift;;
+    --timeout) FTIMEOUT="$2"; shift 2;;
+    *) eyes_die "unknown arg: $1";;
+  esac
+done
+
+docker ps --format '{{.Names}}' | grep -Fxq "$CONTAINER" \
+  || docker ps --format '{{.ID}}' | grep -q "^$CONTAINER" \
+  || eyes_die "container not running: $CONTAINER"
+
+if [ "$FOLLOW" -eq 1 ]; then
+  if [ -n "$PATTERN" ]; then
+    eyes_timeout "$FTIMEOUT" docker logs --tail "$LINES" -f $SINCE "$CONTAINER" 2>&1 | grep --line-buffered -E "$PATTERN" | eyes_redact
+  else
+    eyes_timeout "$FTIMEOUT" docker logs --tail "$LINES" -f $SINCE "$CONTAINER" 2>&1 | eyes_redact
+  fi
+else
+  if [ -n "$PATTERN" ]; then
+    docker logs --tail "$LINES" $SINCE "$CONTAINER" 2>&1 | grep -E "$PATTERN" | eyes_redact || true
+  else
+    docker logs --tail "$LINES" $SINCE "$CONTAINER" 2>&1 | eyes_redact
+  fi
+fi

package/probes/runtime_logs/impl/simctl.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# impl: simctl
+# iOS simulator log stream (last N lines).
+#
+# Usage:
+#   logs-ios.sh [--device <udid>] [--lines N] [--grep <pattern>] [--bundle <id>]
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/_lib.sh"
+
+eyes_require xcrun
+
+DEVICE="booted"
+LINES=200
+PATTERN=""
+BUNDLE=""
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --device) DEVICE="$2"; shift 2;;
+    --lines) LINES="$2"; shift 2;;
+    --grep) PATTERN="$2"; shift 2;;
+    --bundle) BUNDLE="$2"; shift 2;;
+    *) eyes_die "unknown arg: $1";;
+  esac
+done
+
+if [ "$DEVICE" = "booted" ]; then
+  xcrun simctl list devices booted 2>/dev/null | grep -q Booted \
+    || eyes_die "no iOS simulator booted"
+fi
+
+PREDICATE=""
+[ -n "$BUNDLE" ] && PREDICATE="--predicate 'subsystem == \"$BUNDLE\"'"
+
+# `log show` gives historical logs; simpler and bounded than `log stream`.
+OUT="$(eyes_timeout 15 xcrun simctl spawn "$DEVICE" log show --last 3m --style compact $PREDICATE 2>/dev/null | tail -n "$LINES" || true)"
+if [ -n "$PATTERN" ]; then
+  echo "$OUT" | grep -E "$PATTERN" | eyes_redact || true
+else
+  echo "$OUT" | eyes_redact
+fi

package/probes/runtime_logs/impl/tail.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# impl: tail
+# Generic log probe. By convention, up.sh redirects every started process's
+# stdout+stderr into .gg/eyes/out/<service>.log. This probe reads from there OR
+# any arbitrary file path the caller gives it.
+#
+# Usage:
+#   logs.sh [--file <path>] [--service <name>] [--lines N] [--follow --timeout S] [--grep <pattern>]
+#
+# Prints the (redacted) tail to stdout.
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/_lib.sh"
+
+FILE=""
+SERVICE=""
+LINES=100
+FOLLOW=0
+FTIMEOUT=5
+PATTERN=""
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --file) FILE="$2"; shift 2;;
+    --service) SERVICE="$2"; shift 2;;
+    --lines) LINES="$2"; shift 2;;
+    --follow) FOLLOW=1; shift;;
+    --timeout) FTIMEOUT="$2"; shift 2;;
+    --grep) PATTERN="$2"; shift 2;;
+    *) eyes_die "unknown arg: $1";;
+  esac
+done
+
+if [ -z "$FILE" ]; then
+  if [ -n "$SERVICE" ]; then
+    FILE="$(eyes_out_dir)/$SERVICE.log"
+  else
+    eyes_die "provide --file <path> or --service <name>"
+  fi
+fi
+[ -f "$FILE" ] || eyes_die "log file not found: $FILE (did you start the service via .gg/eyes/up.sh?)"
+
+if [ "$FOLLOW" -eq 1 ]; then
+  if [ -n "$PATTERN" ]; then
+    eyes_timeout "$FTIMEOUT" tail -n "$LINES" -f "$FILE" | grep --line-buffered -E "$PATTERN" | eyes_redact
+  else
+    eyes_timeout "$FTIMEOUT" tail -n "$LINES" -f "$FILE" | eyes_redact
+  fi
+else
+  if [ -n "$PATTERN" ]; then
+    tail -n "$LINES" "$FILE" | grep -E "$PATTERN" | eyes_redact || true
+  else
+    tail -n "$LINES" "$FILE" | eyes_redact
+  fi
+fi

package/probes/runtime_logs/install.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# install.sh <impl> [--as <name>]
+set -euo pipefail
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$HERE/../../shared/_lib.sh"
+
+IMPL="${1:-}"
+[ -z "$IMPL" ] && eyes_die "usage: install.sh <impl> [--as <name>]"
+shift
+NAME="logs"
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --as) NAME="$2"; shift 2;;
+    *) eyes_die "unknown arg: $1";;
+  esac
+done
+
+IMPL_FILE="$HERE/impl/$IMPL.sh"
+[ -f "$IMPL_FILE" ] || eyes_die "no impl: $IMPL"
+
+case "$IMPL" in
+  adb-logcat) eyes_require adb;;
+  simctl)     [ "$(eyes_os)" = "darwin" ] || eyes_die "simctl only on macOS"; eyes_require xcrun;;
+  docker)     eyes_require docker;;
+  tail)       : ;;
+  *) eyes_die "unknown impl: $IMPL";;
+esac
+
+DEST="$(eyes_root)/$NAME.sh"
+cp "$IMPL_FILE" "$DEST"
+chmod +x "$DEST"
+cp "$HERE/../../shared/_lib.sh" "$(eyes_root)/_lib.sh"
+cp "$HERE/../../shared/_redact.sh" "$(eyes_root)/_redact.sh"
+chmod +x "$(eyes_root)/_redact.sh"
+
+echo "installed: $DEST (impl=$IMPL)" >&2

package/probes/runtime_logs/test.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# test.sh [name]
+# Tail-based e2e: write a known line to a temp file, tail --since-start, confirm we see it.
+# For adb-logcat / simctl / docker we just verify the tool responds (no target to guarantee).
+set -euo pipefail
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$HERE/../../shared/_lib.sh"
+
+NAME="${1:-logs}"
+PROBE="$(eyes_root)/$NAME.sh"
+[ -x "$PROBE" ] || eyes_die "probe not installed: $PROBE"
+
+IMPL_HINT="$(grep -m1 '^# impl:' "$PROBE" | awk '{print $3}' || true)"
+
+case "$IMPL_HINT" in
+  tail)
+    TMP="$(mktemp)"
+    trap 'rm -f "$TMP"' EXIT
+    printf 'line1\nline2 sk-proj-should-redact-xxxxxxxxx\nline3\n' > "$TMP"
+    OUT="$("$PROBE" --file "$TMP" --lines 3)"
+    echo "$OUT" | grep -q 'line3' || eyes_die "tail probe did not return tail of file"
+    echo "$OUT" | grep -q 'REDACTED_OPENAI' || eyes_die "tail probe did not redact"
+    echo "ok"
+    ;;
+  adb-logcat)
+    adb get-state >/dev/null 2>&1 || eyes_die "no android device; cannot verify"
+    "$PROBE" --lines 5 >/dev/null
+    echo "ok"
+    ;;
+  simctl)
+    xcrun simctl list devices booted 2>/dev/null | grep -q Booted || eyes_die "no iOS simulator booted"
+    "$PROBE" --lines 5 >/dev/null
+    echo "ok"
+    ;;
+  docker)
+    docker ps >/dev/null 2>&1 || eyes_die "docker not running; cannot verify"
+    # Find any running container to tail
+    C="$(docker ps --format '{{.Names}}' | head -1 || true)"
+    [ -n "$C" ] || { echo "ok (no containers to tail, but docker works)"; exit 0; }
+    "$PROBE" "$C" --lines 3 >/dev/null
+    echo "ok"
+    ;;
+  *) eyes_die "unknown impl hint: $IMPL_HINT";;
+esac