BraiinsRatchet/scripts/ratchet

#!/usr/bin/env bash
set -euo pipefail

ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
PYTHON_BIN="$ROOT_DIR/.venv/bin/python"

usage() {
  cat <<'USAGE'
Braiins Ratchet

Commands:
  next               Show exactly what to do next. Default command.
  setup              Create the local .venv and initialize the local database.
  once               Fetch one fresh sample, then print the cockpit.
  watch [hours]      Run repeated monitor cycles for N hours. Default: 6.
  supervise          Run the durable forever lifecycle supervisor.
  engine             Start/stop/status for the background monitor engine.
  app                Build and open the native macOS app.
  mirror             Print the app's latest self-written visual-state snapshot.
  position           Record/list/close manually executed Braiins exposure.
  report             Print the latest stored report without fetching new data.
  app-state          Print structured JSON for the native macOS app.
  experiments        Print the Karpathy-style experiment ledger.
  retro SINCE [UNTIL] Write a retroactive report from stored snapshots.
  raw-cycle          Run one full monitor cycle and print raw JSON.
  test               Run the network-free test suite.
  guide              Print the noob-friendly user guide.
  operator-guide     Print the installation, migration, and recovery guide.
  explain            Alias for guide.

Examples:
  ./scripts/ratchet
  ./scripts/ratchet next
  ./scripts/ratchet setup
  ./scripts/ratchet once
  ./scripts/ratchet watch 6
  ./scripts/ratchet supervise
  ./scripts/ratchet engine status
  ./scripts/ratchet app
  ./scripts/ratchet mirror
  ./scripts/ratchet position list
  ./scripts/ratchet report
  ./scripts/ratchet experiments
  ./scripts/ratchet guide
  ./scripts/ratchet operator-guide
  ./scripts/ratchet retro 2026-04-25T19:08:00+00:00 2026-04-25T21:05:00+00:00
USAGE
}

ensure_venv() {
  if [[ ! -x "$PYTHON_BIN" ]]; then
    echo "Creating local virtual environment at .venv ..." >&2
    python3 -m venv "$ROOT_DIR/.venv"
  fi
}

run_python() {
  ensure_venv
  PYTHONPATH="$ROOT_DIR/src" "$PYTHON_BIN" "$@"
}

cmd_setup() {
  ensure_venv
  run_python -m braiins_ratchet.cli init-db
  echo
  echo "Setup complete. Next: ./scripts/ratchet next"
}

cmd_next() {
  run_python -m braiins_ratchet.cli next
}

cmd_once() {
  run_python -m braiins_ratchet.cli cycle >/dev/null
  echo
  echo "Fresh sample collected. Reading the cockpit now."
  echo "Technical report is available with: ./scripts/ratchet report"
  echo
  run_python -m braiins_ratchet.cli next
}

cmd_raw_cycle() {
  run_python -m braiins_ratchet.cli cycle
}

cmd_watch() {
  local hours="${1:-6}"
  local interval_seconds=300
  local cycles

  if ! [[ "$hours" =~ ^[0-9]+$ ]] || [[ "$hours" -lt 1 ]]; then
    echo "watch expects whole hours, e.g. ./scripts/ratchet watch 6" >&2
    exit 2
  fi

  cycles=$((hours * 3600 / interval_seconds))
  echo "Watch started. This terminal is now controlled by Braiins Ratchet for about $hours hour(s)."
  echo "You do not need to babysit it. Leave this terminal open and come back later."
  echo "It will run $cycles cycles, one cycle every $interval_seconds seconds."
  echo "It only reads public/OCEAN data and writes local snapshots inside this repo."
  echo "At the end it writes reports/EXPERIMENT_LOG.md plus a run report, then prints DO THIS NOW."
  echo "Stop early only if you intentionally want a partial run: Ctrl-C."
  echo

  set +e
  run_python -m braiins_ratchet.cli watch --cycles "$cycles" --interval-seconds "$interval_seconds"
  local status=$?
  set -e
  if [[ "$status" -ne 0 && "$status" -ne 130 ]]; then
    exit "$status"
  fi
  echo
  echo "Watch finished. Reading the cockpit now."
  echo
  BRAIINS_RATCHET_IGNORE_PROCESS_WATCH=1 run_python -m braiins_ratchet.cli next
  return "$status"
}

cmd_report() {
  run_python -m braiins_ratchet.cli report
}

cmd_app_state() {
  run_python -m braiins_ratchet.cli app-state
}

cmd_pipeline() {
  run_python -m braiins_ratchet.cli pipeline "$@"
}

cmd_supervise() {
  run_python -m braiins_ratchet.cli supervise "$@"
}

cmd_engine() {
  run_python -m braiins_ratchet.cli engine "$@"
}

cmd_app() {
  local app_path
  app_path="$("$ROOT_DIR/scripts/build_mac_app" | tail -n 1)"
  echo "Opening $app_path"
  pkill -x BraiinsRatchetMac 2>/dev/null || true
  open "$app_path"
}

cmd_mirror() {
  local path="$ROOT_DIR/data/app_visual_state.md"
  if [[ ! -f "$path" ]]; then
    echo "No app visual-state snapshot exists yet."
    echo "Open the native app with: ./scripts/ratchet app"
    echo "Then refresh or open the Reality Mirror tab."
    return 0
  fi
  cat "$path"
}

cmd_position() {
  run_python -m braiins_ratchet.cli position "$@"
}

cmd_experiments() {
  run_python -m braiins_ratchet.cli experiments
}

cmd_retro() {
  local since="${1:-}"
  local until="${2:-}"
  local run_id

  if [[ -z "$since" ]]; then
    echo "retro expects an ISO timestamp, e.g. ./scripts/ratchet retro 2026-04-25T19:08:00+00:00" >&2
    exit 2
  fi

  run_id="retro-${since//[:+]/-}"
  if [[ -n "$until" ]]; then
    run_python -m braiins_ratchet.cli retro-report --since "$since" --until "$until" --run-id "$run_id" --write
  else
    run_python -m braiins_ratchet.cli retro-report --since "$since" --run-id "$run_id" --write
  fi
}

cmd_test() {
  run_python -m unittest discover -s "$ROOT_DIR/tests"
}

cmd_explain() {
  cat "$ROOT_DIR/docs/USER_GUIDE.md"
}

cmd_operator_guide() {
  cat "$ROOT_DIR/docs/OPERATOR_GUIDE.md"
}

main() {
  cd "$ROOT_DIR"
  local command="${1:-next}"
  shift || true

  case "$command" in
    next) cmd_next "$@" ;;
    setup) cmd_setup "$@" ;;
    once) cmd_once "$@" ;;
    watch) cmd_watch "$@" ;;
    pipeline|auto) cmd_pipeline "$@" ;;
    supervise|daemon) cmd_supervise "$@" ;;
    engine) cmd_engine "$@" ;;
    app|mac-app) cmd_app "$@" ;;
    mirror|reality) cmd_mirror "$@" ;;
    position|positions) cmd_position "$@" ;;
    report) cmd_report "$@" ;;
    app-state) cmd_app_state "$@" ;;
    experiments) cmd_experiments "$@" ;;
    retro) cmd_retro "$@" ;;
    raw-cycle) cmd_raw_cycle "$@" ;;
    test) cmd_test "$@" ;;
    guide|user-guide|explain) cmd_explain "$@" ;;
    operator-guide|operator) cmd_operator_guide "$@" ;;
    help|-h|--help) usage ;;
    *)
      echo "Unknown command: $command" >&2
      echo >&2
      usage >&2
      exit 2
      ;;
  esac
}

main "$@"