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.
  report             Print the latest stored report without fetching new data.
  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.
  explain            Print the operating procedure and interpretation guide.

Examples:
  ./scripts/ratchet
  ./scripts/ratchet next
  ./scripts/ratchet setup
  ./scripts/ratchet once
  ./scripts/ratchet watch 6
  ./scripts/ratchet report
  ./scripts/ratchet experiments
  ./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 ..."
    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
  run_python -m braiins_ratchet.cli next
  return "$status"
}

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

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/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 "$@" ;;
    report) cmd_report "$@" ;;
    experiments) cmd_experiments "$@" ;;
    retro) cmd_retro "$@" ;;
    raw-cycle) cmd_raw_cycle "$@" ;;
    test) cmd_test "$@" ;;
    explain) cmd_explain "$@" ;;
    help|-h|--help) usage ;;
    *)
      echo "Unknown command: $command" >&2
      echo >&2
      usage >&2
      exit 2
      ;;
  esac
}

main "$@"