@erclx/aitk 0.8.0

package/scripts/lib/sandbox-fixtures.sh

@@ -0,0 +1,109 @@
+#!/usr/bin/env bash
+
+# Fixture files carry this suffix so the repository's own checks ignore them.
+# A stored `index.md.fixture` is not an `index.md`, so the index walker, prettier,
+# shfmt, and shellcheck all skip it and the bytes reach the sandbox unmodified.
+FIXTURE_SUFFIX=".fixture"
+
+# The tree mirrors the scenario path, so `category` and `scenario` together match
+# `scripts/sandbox/<category>/<scenario>.sh`. Both segments are load-bearing:
+# four scenario basenames repeat across categories (`claude`, `docs`, `review`,
+# `sync`), and `docs` is also a category of its own.
+fixture_stage_dir() {
+  local category="$1"
+  local scenario="$2"
+  local arm="$3"
+  local stage="$4"
+  echo "$PROJECT_ROOT/scripts/sandbox/fixtures/$category/$scenario/$arm/$stage"
+}
+
+list_fixture_files() {
+  local source_dir="$1"
+  find "$source_dir" -type f -name "*$FIXTURE_SUFFIX" -print0 | sort -z
+}
+
+count_fixture_files() {
+  local source_dir="$1"
+  if [ ! -d "$source_dir" ]; then
+    echo 0
+    return 0
+  fi
+  find "$source_dir" -type f -name "*$FIXTURE_SUFFIX" | wc -l
+}
+
+# The copy loops match on the suffix, so a file without one would be skipped in
+# silence and the scenario would provision a tree it was never meant to have.
+assert_fixtures_suffixed() {
+  local source_dir="$1"
+  [ -d "$source_dir" ] || return 0
+
+  local stray
+  stray="$(find "$source_dir" -type f -not -name "*$FIXTURE_SUFFIX" | sort | tr '\n' ' ')"
+  [ -z "$stray" ] || log_error "Fixture missing the $FIXTURE_SUFFIX suffix: $stray"
+}
+
+fixture_target_path() {
+  local source_dir="$1"
+  local source_file="$2"
+  local relative="${source_file#"$source_dir"/}"
+  echo "${relative%"$FIXTURE_SUFFIX"}"
+}
+
+create_from_fixtures() {
+  local source_dir="$1"
+  [ -d "$source_dir" ] || return 0
+
+  local source_file target
+  while IFS= read -r -d '' source_file; do
+    target="$(fixture_target_path "$source_dir" "$source_file")"
+    mkdir -p "$(dirname "$target")"
+    cp "$source_file" "$target"
+  done < <(list_fixture_files "$source_dir")
+}
+
+# An append fixture extends a file the anchor or the injected seeds already
+# provide. A missing target means that upstream shape changed, so fail rather
+# than create the file and silently alter what the scenario provisions.
+append_from_fixtures() {
+  local source_dir="$1"
+  [ -d "$source_dir" ] || return 0
+
+  local source_file target
+  while IFS= read -r -d '' source_file; do
+    target="$(fixture_target_path "$source_dir" "$source_file")"
+    if [ ! -f "$target" ]; then
+      log_error "Append fixture has no target: $target"
+    fi
+    cat "$source_file" >>"$target"
+  done < <(list_fixture_files "$source_dir")
+}
+
+# Stages one step of a scenario arm into the sandbox working directory.
+# Scenarios call this once per step so their own git operations stay between
+# the steps, where they are visible.
+stage_fixtures() {
+  local category="$1"
+  local scenario="$2"
+  local arm="$3"
+  local stage="$4"
+
+  local stage_dir
+  stage_dir="$(fixture_stage_dir "$category" "$scenario" "$arm" "$stage")"
+
+  if [ ! -d "$stage_dir" ]; then
+    log_error "Fixture stage not found: $category/$scenario/$arm/$stage"
+  fi
+
+  assert_fixtures_suffixed "$stage_dir/create"
+  assert_fixtures_suffixed "$stage_dir/append"
+
+  local staged
+  staged=$(($(count_fixture_files "$stage_dir/create") + \
+  $(count_fixture_files "$stage_dir/append")))
+  if [ "$staged" -eq 0 ]; then
+    log_error "Fixture stage provisions nothing: $category/$scenario/$arm/$stage"
+  fi
+
+  create_from_fixtures "$stage_dir/create"
+  append_from_fixtures "$stage_dir/append"
+}

package/scripts/lib/sandbox-git.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+
+# The sandbox reaches GitHub over HTTPS with the gh token so a headless run needs
+# no SSH key and no agent. `gh auth login` authenticates the CLI but leaves git
+# itself without a credential, so the harness supplies the helper rather than
+# assuming the machine carries one.
+SANDBOX_GIT_CREDENTIAL_HELPER='!gh auth git-credential'
+
+# Call from the main shell before any scenario runs. sandbox_anchor_url is used
+# inside command substitutions, where log_error would exit only the subshell and
+# leave the caller building an empty remote, so the run has to stop here instead.
+require_sandbox_anchor_config() {
+  if [ -z "${GITHUB_ORG:-}" ]; then
+    log_error "GITHUB_ORG is empty. Export GITHUB_ORG=<org>, or run from a clone whose remote.origin.url points at GitHub."
+  fi
+}
+
+sandbox_anchor_url() {
+  local repo_name="${1:-${ANCHOR_REPO:-}}"
+
+  if [ -z "$repo_name" ] || [ -z "${GITHUB_ORG:-}" ]; then
+    log_error "sandbox_anchor_url needs GITHUB_ORG and a repository name. Call require_sandbox_anchor_config first."
+  fi
+
+  printf 'https://github.com/%s/%s.git\n' "$GITHUB_ORG" "$repo_name"
+}
+
+# credential.helper is multi-valued and git concatenates it across system, global,
+# and local, trying each in order until one returns a credential. A plain set
+# leaves an operator's existing helper ahead of this one, so a stale token wins
+# and gh never runs. The empty value resets the inherited list first.
+configure_sandbox_git_credentials() {
+  git config credential.helper ""
+  git config --add credential.helper "$SANDBOX_GIT_CREDENTIAL_HELPER"
+}
+
+resolve_sandbox_git_identity() {
+  SANDBOX_GIT_NAME="${SANDBOX_GIT_NAME:-$(git config --global user.name 2>/dev/null || true)}"
+  SANDBOX_GIT_EMAIL="${SANDBOX_GIT_EMAIL:-$(git config --global user.email 2>/dev/null || true)}"
+
+  : "${SANDBOX_GIT_NAME:=aitk-sandbox}"
+  : "${SANDBOX_GIT_EMAIL:=sandbox@example.com}"
+
+  export SANDBOX_GIT_NAME SANDBOX_GIT_EMAIL
+}
+
+configure_sandbox_git_identity() {
+  resolve_sandbox_git_identity
+  git config user.name "$SANDBOX_GIT_NAME"
+  git config user.email "$SANDBOX_GIT_EMAIL"
+}
+
+# Every scenario that needs a remote points at the same throwaway repository, so
+# the name lives here rather than in each one.
+SANDBOX_ANCHOR_REPO="toolkit-sandbox"
+
+# A scenario calls this from its own use_anchor hook rather than this file
+# defining the hook. manage-sandbox.sh keys off `type -t use_anchor`, so
+# declaring it here would hand an anchor to the scenarios that source this file
+# for the identity helpers alone.
+use_sandbox_anchor() {
+  export ANCHOR_REPO="${1:-$SANDBOX_ANCHOR_REPO}"
+}
+
+# A remote is useless without an author, so the scenarios that reach one always
+# configure both. configure_sandbox_git_identity stays callable on its own for
+# the scenarios that never push. The remove keeps this idempotent against a
+# sandbox tree that already carries an origin.
+configure_sandbox_anchor_remote() {
+  configure_sandbox_git_identity
+  git remote remove origin 2>/dev/null || true
+  git remote add origin "$(sandbox_anchor_url "$@")"
+}

package/scripts/lib/tooling.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+
+TOOLING_STACK_EXCLUDE=("claude")
+
+is_tooling_stack_excluded() {
+  local name="$1"
+  local excluded
+  for excluded in "${TOOLING_STACK_EXCLUDE[@]}"; do
+    if [ "$name" = "$excluded" ]; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+list_tooling_stacks() {
+  local tooling_dir="${1:-$PROJECT_ROOT/tooling}"
+  local name
+  while IFS= read -r entry; do
+    name=$(basename "$entry")
+    is_tooling_stack_excluded "$name" && continue
+    echo "$name"
+  done < <(find "$tooling_dir" -mindepth 1 -maxdepth 1 -type d | sort)
+}

package/scripts/lib/ui.sh

@@ -0,0 +1,173 @@
+#!/usr/bin/env bash
+
+if [ "${BASH_VERSINFO[0]:-0}" -lt 4 ]; then
+  echo "aitk requires bash 4 or newer. Current: ${BASH_VERSION:-unknown}." >&2
+  echo "Install via Homebrew: brew install bash" >&2
+  exit 1
+fi
+
+GREEN='\033[0;32m'
+RED='\033[0;31m'
+YELLOW='\033[0;33m'
+WHITE='\033[1;37m'
+GREY='\033[0;90m'
+NC='\033[0m'
+
+log_info() { echo -e "${GREY}│${NC} ${GREEN}✓${NC} $1" >&2; }
+log_warn() { echo -e "${GREY}│${NC} ${YELLOW}!${NC} $1" >&2; }
+log_error() {
+  echo -e "${GREY}│${NC} ${RED}✗${NC} $1" >&2
+  exit 1
+}
+log_step() { echo -e "${GREY}│${NC}\n${GREY}├${NC} ${WHITE}$1${NC}" >&2; }
+log_add() { echo -e "${GREY}│${NC} ${GREEN}+${NC} $1" >&2; }
+log_rem() { echo -e "${GREY}│${NC} ${RED}-${NC} $1" >&2; }
+
+pipe_output() { while IFS= read -r line; do echo -e "${GREY}│${NC}  $line" >&2; done; }
+
+open_timeline() {
+  echo -e "${GREY}┌${NC}" >&2
+  if [ -n "${1:-}" ]; then
+    echo -e "${GREY}│${NC} ${WHITE}$1${NC}" >&2
+  fi
+}
+
+close_timeline() {
+  echo -e "${GREY}└${NC}" >&2
+}
+
+guard_root() {
+  local target="$1"
+  local target_abs
+  target_abs=$(cd "$target" && pwd)
+  if [ "$target_abs" = "$PROJECT_ROOT" ]; then
+    log_error "Cannot run against toolkit root. Files here are the source of truth."
+  fi
+}
+
+require_project_root() {
+  if [[ "$PWD" == *".sandbox"* ]]; then
+    echo -e "${GREY}┌${NC}" >&2
+    log_error "Execution restricted: Command cannot be run from inside the sandbox environment."
+  fi
+  if [[ "$PWD" != "$PROJECT_ROOT"* ]]; then
+    echo -e "${GREY}┌${NC}" >&2
+    log_error "Context Error: You must run this command from inside the repository."
+  fi
+}
+
+ask() {
+  local prompt_text=$1
+  local var_name=$2
+  local default_val=$3
+  local input=""
+  local char
+  local display_default=""
+  if [ -n "$default_val" ]; then
+    display_default=" (${default_val})"
+  fi
+  if [[ "${AITK_NON_INTERACTIVE:-}" == "1" ]]; then
+    echo -e "${GREY}│${NC}" >&2
+    echo -e "${GREY}◇${NC} ${prompt_text} ${WHITE}${default_val}${NC}" >&2
+    export "$var_name"="$default_val"
+    return
+  fi
+  echo -e "${GREY}│${NC}" >&2
+  echo -ne "${GREEN}◆${NC} ${prompt_text}${display_default} " >&2
+  while IFS= read -r -s -n1 char; do
+    if [[ $char == $'\x1b' ]]; then
+      read -rsn2 -t 0.001 _ || true
+      echo -ne "\r\033[K" >&2
+      echo -e "${GREY}◇${NC} ${prompt_text} ${RED}Cancelled${NC}" >&2
+      exit 1
+    elif [[ $char == $'\x7f' || $char == $'\x08' ]]; then
+      if [ -n "$input" ]; then
+        input="${input%?}"
+        echo -ne "\b \b" >&2
+      fi
+    elif [[ -z "$char" ]]; then
+      break
+    else
+      input+="$char"
+      echo -n "$char" >&2
+    fi
+  done
+  [ -z "$input" ] && input="$default_val"
+  echo -ne "\r\033[K" >&2
+  echo -e "${GREY}◇${NC} ${prompt_text} ${WHITE}${input}${NC}" >&2
+  export "$var_name"="$input"
+}
+
+select_or_route_scenario() {
+  local prompt_text=$1
+  shift
+  local options=("$@")
+
+  if [ -n "${SANDBOX_SCENARIO:-}" ]; then
+    echo -e "${GREY}│${NC}" >&2
+    echo -e "${GREY}◇${NC} ${prompt_text} ${WHITE}${SANDBOX_SCENARIO}${NC}" >&2
+    export SELECTED_OPTION="$SANDBOX_SCENARIO"
+    return
+  fi
+
+  select_option "$prompt_text" "${options[@]}"
+}
+
+select_option() {
+  local prompt_text=$1
+  shift
+  local options=("$@")
+  local cur=0
+  local count=${#options[@]}
+
+  if [[ "${AITK_NON_INTERACTIVE:-}" == "1" ]]; then
+    echo -e "${GREY}│${NC}" >&2
+    echo -e "${GREY}◇${NC} ${prompt_text} ${WHITE}${options[0]}${NC}" >&2
+    export SELECTED_OPTION="${options[0]}"
+    return
+  fi
+
+  if [ ! -t 0 ]; then
+    log_error "${prompt_text} requires a TTY. Pass an argument or set AITK_NON_INTERACTIVE=1."
+  fi
+
+  echo -e "${GREY}│${NC}" >&2
+  echo -ne "${GREEN}◆${NC} ${prompt_text}\n" >&2
+
+  while true; do
+    for i in "${!options[@]}"; do
+      if [ "$i" -eq "$cur" ]; then
+        echo -e "${GREY}│${NC}  ${GREEN}❯ ${options[$i]}${NC}" >&2
+      else
+        echo -e "${GREY}│${NC}    ${GREY}${options[$i]}${NC}" >&2
+      fi
+    done
+
+    read -rsn1 key
+    case "$key" in
+    $'\x1b')
+      if read -rsn2 -t 0.001 key_seq; then
+        if [[ "$key_seq" == "[A" ]]; then cur=$(((cur - 1 + count) % count)); fi
+        if [[ "$key_seq" == "[B" ]]; then cur=$(((cur + 1) % count)); fi
+      else
+        echo -ne "\033[$((count + 1))A\033[J" >&2
+        echo -e "${GREY}◇${NC} ${prompt_text} ${RED}Cancelled${NC}" >&2
+        exit 1
+      fi
+      ;;
+    "k") cur=$(((cur - 1 + count) % count)) ;;
+    "j") cur=$(((cur + 1) % count)) ;;
+    "q")
+      echo -ne "\033[$((count + 1))A\033[J" >&2
+      echo -e "${GREY}◇${NC} ${prompt_text} ${RED}Cancelled${NC}" >&2
+      exit 1
+      ;;
+    "") break ;;
+    esac
+    echo -ne "\033[${count}A" >&2
+  done
+
+  echo -ne "\033[$((count + 1))A\033[J" >&2
+  echo -e "${GREY}◇${NC} ${prompt_text} ${WHITE}${options[$cur]}${NC}" >&2
+  export SELECTED_OPTION="${options[$cur]}"
+}

package/scripts/lib/worktree.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+
+# Claude Code's worktree entry writes core.bare into the parent repository's
+# shared config and its exit never restores it, stranding every later command in
+# the main worktree. Sourced by verify.sh, which runs the repair before any stage
+# because the flag breaks the git reads that scope the run.
+
+repair_bare_flag() {
+  local root="${1:-$PROJECT_ROOT}"
+  local common_dir
+  [ "$(git -C "$root" config --get core.bare 2>/dev/null || echo false)" = true ] || return 0
+
+  common_dir=$(git -C "$root" rev-parse --path-format=absolute --git-common-dir 2>/dev/null) || return 0
+  # A genuinely bare repository keeps its objects at the root and has no .git
+  # directory, so it fails this test and keeps its flag.
+  [ "$(basename "$common_dir")" = ".git" ] || return 0
+
+  git -C "$root" config core.bare false
+  log_warn "Repaired core.bare, which worktree entry left set. Recovery is 'git config core.bare false'."
+}