Running (part of) the ci specification file locally.

[thorwhalen]

By that, I mean when things like black or pytest have particular arguments, being able to use those (instead of repeatedly being the situation of "why doesn't it work?.... Oh, yeah, I need to ignore such an such a folder when I test...".

A lot of particulars are defined in the ci def file (e.g. ci.yml in github), it'd be nice to reuse these!

So I imagine doing something like this in the terminal

$ isee local PROJECT_ROOT_FOLDER

That would trigger something like:

• Extract information from ci definition file (what is extracted can be configured)
• Run some processes (parametrized by the info we extracted) locally

[thorwhalen]

My guess is that this won't be too hard for a basic version.

• Specify some patterns that will match the lines that should be extracted
• Run these lines (possibly modified to refer to the right project, or after CDing to the right project so that the dot refers to the right folder) using subprocess module.

[thorwhalen]

ACT

ACT is a tool for running github actions locally.
Should probably use that to implement our desired functionality.

Manual instructions to set ACT up

Practical setup for running GitHub Actions locally with act (idempotent-aware)
1. Verify Docker is installed and running.
• Check: docker --version and docker info
• If the CLI is missing, install Docker Desktop (macOS) via Homebrew Cask or your
Linux package manager.
• If the daemon isn’t running, start Docker Desktop (macOS) or systemctl start docker
(Linux). Add your user to the docker group on Linux if needed.
2. Verify act is installed.
• Check: act --version
• If missing, install via Homebrew (brew install act) or the official install script
(curl .../nektos/act/.../install.sh | sudo bash).
3. Verify workflows exist and choose how to run.
• Check: .github/workflows/ contains YAML files
• Optional: create a ~/.actrc (or keep your existing one) to pin defaults
(runner image mapping, container architecture).
• Optional: create local .secrets and .vars files (KEY=VALUE lines).
• List jobs: act -l
• Run: act (all jobs for push), or target -j / -W ; pass
--secret-file .secrets / --var-file .vars if you created them.

Bash script: idempotent bootstrap + guided first run

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

# Idempotent setup for running GitHub Actions locally with `act`.
# - Verifies Docker (CLI + daemon) and `act`
# - Optionally installs missing pieces
# - Preserves existing config; offers updates
# - Optionally creates .secrets and .vars
# - Lists and optionally runs workflows

msg() { printf "\n%s\n" "$*"; }
err() { printf "\nERROR: %s\n" "$*" >&2; }
ask_yn() {
  local prompt="$1" default="${2:-Y}" reply
  local suffix="[Y/n]"; [[ "$default" =~ ^[Nn]$ ]] && suffix="[y/N]"
  read -r -p "$prompt $suffix " reply || true
  reply="${reply:-$default}"
  [[ "$reply" =~ ^[Yy]$ ]]
}
need_cmd() { command -v "$1" >/dev/null 2>&1; }

OS="$(uname -s | tr '[:upper:]' '[:lower:]')"
ARCH="$(uname -m)"
PKG=""
if need_cmd brew; then PKG="brew"
elif need_cmd apt-get; then PKG="apt"
elif need_cmd dnf; then PKG="dnf"
elif need_cmd pacman; then PKG="pacman"
fi

ensure_docker_cli() {
  if need_cmd docker; then
    msg "Docker CLI found: $(docker --version 2>/dev/null | head -n1)"
    return
  fi
  msg "Docker CLI not found."
  if ask_yn "Install Docker now?" "N"; then
    if [[ "$OS" == "darwin" ]]; then
      if [[ "$PKG" == "brew" ]]; then
        brew install --cask docker
      else
        err "Homebrew not available. Install Docker Desktop manually."
        exit 1
      fi
    elif [[ "$OS" == "linux" ]]; then
      if [[ "$PKG" == "apt" ]]; then
        sudo apt-get update
        sudo apt-get install -y docker.io
      elif [[ "$PKG" == "dnf" ]]; then
        sudo dnf -y install docker
      elif [[ "$PKG" == "pacman" ]]; then
        sudo pacman -Sy --noconfirm docker
      else
        err "Unknown package manager. Install Docker for your distro manually."
        exit 1
      fi
    else
      err "Unsupported OS for automated Docker install."
      exit 1
    fi
  else
    err "Docker is required. Aborting."
    exit 1
  fi
}

ensure_docker_daemon() {
  if docker info >/dev/null 2>&1; then
    msg "Docker daemon is running."
    return
  fi
  msg "Docker daemon not running."

  if [[ "$OS" == "darwin" ]]; then
    if ask_yn "Start Docker Desktop now?" "Y"; then
      open -g -a "Docker.app" || true
      for i in {1..60}; do
        docker info >/dev/null 2>&1 && break
        sleep 2
      done
      docker info >/dev/null 2>&1 || { err "Docker did not become ready."; exit 1; }
    else
      err "Start Docker Desktop and re-run."
      exit 1
    fi
  elif [[ "$OS" == "linux" ]]; then
    if need_cmd systemctl; then
      if ask_yn "Start docker service with systemd now?" "Y"; then
        sudo systemctl enable --now docker
      else
        err "Start docker (`sudo systemctl start docker`) and re-run."
        exit 1
      fi
      if ! groups "$USER" | grep -q "\bdocker\b"; then
        if ask_yn "Add $USER to 'docker' group (no sudo for docker)?" "Y"; then
          sudo usermod -aG docker "$USER" || true
          msg "You may need to log out/in (or run: newgrp docker)."
        fi
      fi
    else
      err "systemd not found. Start your Docker daemon manually and re-run."
      exit 1
    fi
  else
    err "Unsupported OS for automated daemon start."
    exit 1
  fi
}

ensure_act() {
  if need_cmd act; then
    msg "act found: $(act --version 2>/dev/null | head -n1)"
    return
  fi
  msg "act not found."
  if ask_yn "Install act now?" "Y"; then
    if [[ "$PKG" == "brew" ]]; then
      brew install act
    else
      # Official installer (portable)
      curl --proto '=https' --tlsv1.2 -sSf \
        https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
    fi
    msg "act installed: $(act --version 2>/dev/null | head -n1)"
  else
    err "act is required to run workflows locally."
    exit 1
  fi
}

configure_actrc() {
  local actrc="$HOME/.actrc"
  local have_actrc="no"
  [[ -f "$actrc" ]] && have_actrc="yes"

  if [[ "$have_actrc" == "yes" ]]; then
    msg "Existing ~/.actrc detected."
    if ask_yn "Keep existing ~/.actrc as-is?" "Y"; then
      return
    fi
  fi

  if ask_yn "Create/update ~/.actrc with sensible defaults?" "Y"; then
    local arch="linux/amd64"
    case "$ARCH" in
      arm64|aarch64) arch="linux/arm64" ;;
    esac

    # Minimal defaults: map ubuntu-latest and set container architecture.
    # (Leave the runner image generic; act will prompt/pull on first run.)
    {
      echo "--container-architecture $arch"
      echo "-P ubuntu-latest=catthehacker/ubuntu:act-latest"
      echo "-P ubuntu-22.04=catthehacker/ubuntu:act-22.04"
      echo "-P ubuntu-24.04=catthehacker/ubuntu:act-24.04"
    } > "$actrc"
    msg "Wrote defaults to $actrc"
  fi
}

maybe_make_file() {
  local file="$1" label="$2"
  if [[ -f "$file" ]]; then
    msg "$file already exists."
    if ask_yn "Append more $label entries to $file?" "N"; then
      while true; do
        read -r -p "Add $label entry KEY=VALUE (empty to finish): " line || true
        [[ -z "${line}" ]] && break
        if [[ "$line" == *"="* ]]; then
          echo "$line" >> "$file"
        else
          msg "Use KEY=VALUE format."
        fi
      done
    fi
  else
    if ask_yn "Create $file for $label?" "N"; then
      : > "$file"
      while true; do
        read -r -p "Add $label entry KEY=VALUE (empty to finish): " line || true
        [[ -z "${line}" ]] && break
        if [[ "$line" == *"="* ]]; then
          echo "$line" >> "$file"
        else
          msg "Use KEY=VALUE format."
        fi
      done
      msg "Wrote $(wc -l < "$file") entries to $file"
    fi
  fi
}

list_and_run() {
  if [[ ! -d .github/workflows ]]; then
    msg "No .github/workflows directory found in current path: $(pwd)"
    return
  fi

  msg "Available workflows/jobs:"
  act -l || true

  if ask_yn "Run workflows now?" "N"; then
    local args=()
    [[ -f .secrets ]] && args+=(--secret-file .secrets)
    [[ -f .vars    ]] && args+=(--var-file .vars)

    if ask_yn "Run a specific job?" "N"; then
      read -r -p "Enter job id (from 'act -l'): " job
      act -j "$job" "${args[@]}"
    elif ask_yn "Run a specific workflow file?" "N"; then
      read -r -p "Path to workflow (.github/workflows/ci.yml): " wf
      act -W "$wf" "${args[@]}"
    else
      act "${args[@]}"
    fi
  fi
}

main() {
  msg "== Checking Docker CLI =="
  ensure_docker_cli

  msg "== Checking Docker daemon =="
  ensure_docker_daemon

  msg "== Checking act =="
  ensure_act

  msg "== Configuring ~/.actrc (optional) =="
  configure_actrc

  msg "== Local secrets/vars (optional) =="
  maybe_make_file ".secrets" "secrets"
  maybe_make_file ".vars"    "variables"

  msg "== List and optionally run workflows =="
  list_and_run

  msg "All done."
}

main "$@"