rhachet-roles-ehmpathy 1.10.0 → 1.11.0

package/dist/logic/roles/mechanic/.skills/git.worktree.common.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = shared helpers for git worktree management
+#
+# .why  = centralizes path resolution and branch sanitization logic
+#         used by git.worktree.{get,set,del}.sh scripts
+#
+# .how  = source this file to get access to:
+#           - resolve_worktrees_dir: computes $REPO_WORKTREES_DIR
+#           - sanitize_branch_name: converts branch to worktree name
+#           - get_repo_name: extracts repo name from gitroot
+#
+# guarantee:
+#   - works from root repo or from within a worktree
+#   - consistent path resolution across all worktree scripts
+######################################################################
+
+# resolve the worktrees directory for this repo
+# handles both root repo and worktree contexts
+resolve_worktrees_dir() {
+  local gitroot
+  gitroot="$(git rev-parse --show-toplevel)"
+
+  local reponame
+  reponame="$(basename "$gitroot")"
+
+  # detect if we're in a worktree (path contains _worktrees)
+  if [[ "$gitroot" == *"_worktrees"* ]]; then
+    # we're in a worktree - reuse same _worktrees/$reponame dir
+    echo "${gitroot%/*}"
+  else
+    # root repo - compute sibling _worktrees dir
+    echo "$(dirname "$gitroot")/_worktrees/$reponame"
+  fi
+}
+
+# sanitize branch name for use as directory name
+# vlad/practs => vlad.practs
+sanitize_branch_name() {
+  local branch="$1"
+  echo "${branch//\//.}"
+}
+
+# get the repo name (works from root repo or worktree)
+get_repo_name() {
+  local gitroot
+  gitroot="$(git rev-parse --show-toplevel)"
+
+  # detect if we're in a worktree (path contains _worktrees)
+  if [[ "$gitroot" == *"_worktrees"* ]]; then
+    # extract repo name from _worktrees/$reponame/$worktree path
+    # gitroot = /path/to/_worktrees/$reponame/$worktree
+    local worktrees_parent="${gitroot%/*}"  # /path/to/_worktrees/$reponame
+    basename "$worktrees_parent"
+  else
+    basename "$gitroot"
+  fi
+}

package/dist/logic/roles/mechanic/.skills/git.worktree.del.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = remove a git worktree
+#
+# .why  = clean up worktrees no longer needed
+#
+# .how  = removes worktree at @gitroot/../_worktrees/$reponame/$branch
+#
+# usage:
+#   git.worktree.del.sh <branch>
+#
+# guarantee:
+#   - idempotent: [DELETE] if exists, [SKIP] if not found
+#   - works from root repo or from within a worktree
+######################################################################
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# source shared helpers
+source "$SCRIPT_DIR/git.worktree.common.sh"
+
+# parse arguments
+BRANCH="${1:-}"
+
+# validate branch argument
+if [[ -z "$BRANCH" ]]; then
+  echo "error: branch name required"
+  echo "usage: git.worktree.del.sh <branch>"
+  exit 1
+fi
+
+# resolve paths
+REPO_WORKTREES_DIR="$(resolve_worktrees_dir)"
+WORKTREE_NAME="$(sanitize_branch_name "$BRANCH")"
+WORKTREE_PATH="$REPO_WORKTREES_DIR/$WORKTREE_NAME"
+
+# delete logic
+if [[ -d "$WORKTREE_PATH" ]]; then
+  # remove worktree via git
+  git worktree remove "$WORKTREE_PATH" --force 2>/dev/null || {
+    # fallback: manual removal if git worktree remove fails
+    rm -rf "$WORKTREE_PATH"
+    git worktree prune
+  }
+
+  echo "[DELETE] $WORKTREE_NAME"
+else
+  echo "[SKIP] $WORKTREE_NAME (not found)"
+fi

package/dist/logic/roles/mechanic/.skills/git.worktree.get.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = list git worktrees for this repo
+#
+# .why  = discover existing worktrees managed by git.worktree.sh
+#
+# .how  = lists worktrees at @gitroot/../_worktrees/$reponame/
+#
+# usage:
+#   git.worktree.get.sh
+#
+# guarantee:
+#   - works from root repo or from within a worktree
+#   - shows "(no worktrees)" if none exist
+######################################################################
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# source shared helpers
+source "$SCRIPT_DIR/git.worktree.common.sh"
+
+# resolve worktrees directory
+REPO_WORKTREES_DIR="$(resolve_worktrees_dir)"
+REPO_NAME="$(get_repo_name)"
+
+# check if worktrees directory exists
+if [[ ! -d "$REPO_WORKTREES_DIR" ]]; then
+  echo "(no worktrees)"
+  exit 0
+fi
+
+# list worktrees
+WORKTREES=()
+for dir in "$REPO_WORKTREES_DIR"/*/; do
+  [[ -d "$dir" ]] && WORKTREES+=("$dir")
+done
+
+# handle empty
+if [[ ${#WORKTREES[@]} -eq 0 ]]; then
+  echo "(no worktrees)"
+  exit 0
+fi
+
+# output worktree list
+echo "worktrees for $REPO_NAME:"
+for dir in "${WORKTREES[@]}"; do
+  name="$(basename "$dir")"
+  echo "  $name => $dir"
+done

package/dist/logic/roles/mechanic/.skills/git.worktree.set.sh

@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = findsert a git worktree for a branch
+#
+# .why  = enable parallel work on same repo without nested worktrees
+#         worktrees are placed outside repo so git diff stays clean
+#
+# .how  = creates worktree at @gitroot/../_worktrees/$reponame/$branch
+#
+# usage:
+#   git.worktree.set.sh <branch>            # findsert worktree
+#   git.worktree.set.sh <branch> --open     # findsert + open in codium
+#   git.worktree.set.sh <branch> --main     # create from origin/main
+#
+# guarantee:
+#   - idempotent: [KEEP] if exists, [CREATE] if not
+#   - works from root repo or from within a worktree
+#   - worktree placed outside repo (not nested)
+######################################################################
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# source shared helpers
+source "$SCRIPT_DIR/git.worktree.common.sh"
+
+# parse arguments
+BRANCH=""
+FLAG_OPEN=false
+FLAG_MAIN=false
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --open)
+      FLAG_OPEN=true
+      shift
+      ;;
+    --main)
+      FLAG_MAIN=true
+      shift
+      ;;
+    -*)
+      echo "error: unknown flag '$1'"
+      echo "usage: git.worktree.set.sh <branch> [--open] [--main]"
+      exit 1
+      ;;
+    *)
+      if [[ -z "$BRANCH" ]]; then
+        BRANCH="$1"
+      else
+        echo "error: unexpected argument '$1'"
+        exit 1
+      fi
+      shift
+      ;;
+  esac
+done
+
+# validate branch argument
+if [[ -z "$BRANCH" ]]; then
+  echo "error: branch name required"
+  echo "usage: git.worktree.set.sh <branch> [--open] [--main]"
+  exit 1
+fi
+
+# resolve paths
+REPO_WORKTREES_DIR="$(resolve_worktrees_dir)"
+WORKTREE_NAME="$(sanitize_branch_name "$BRANCH")"
+WORKTREE_PATH="$REPO_WORKTREES_DIR/$WORKTREE_NAME"
+
+# ensure parent directory exists
+mkdir -p "$REPO_WORKTREES_DIR"
+
+# findsert logic
+if [[ -d "$WORKTREE_PATH" ]]; then
+  echo "[KEEP] $WORKTREE_NAME => $WORKTREE_PATH"
+else
+  # create worktree
+  if [[ "$FLAG_MAIN" == true ]]; then
+    # fetch latest main first
+    git fetch origin main 2>/dev/null || git fetch origin master 2>/dev/null || true
+
+    # create new branch from origin/main
+    git worktree add -b "$BRANCH" "$WORKTREE_PATH" origin/main 2>/dev/null || \
+      git worktree add -b "$BRANCH" "$WORKTREE_PATH" origin/master
+  else
+    # check if branch exists
+    if git show-ref --verify --quiet "refs/heads/$BRANCH" 2>/dev/null; then
+      # branch exists locally, checkout existing
+      git worktree add "$WORKTREE_PATH" "$BRANCH"
+    elif git show-ref --verify --quiet "refs/remotes/origin/$BRANCH" 2>/dev/null; then
+      # branch exists on remote, track it
+      git worktree add --track -b "$BRANCH" "$WORKTREE_PATH" "origin/$BRANCH"
+    else
+      # create new branch from current HEAD
+      git worktree add -b "$BRANCH" "$WORKTREE_PATH"
+    fi
+  fi
+
+  echo "[CREATE] $WORKTREE_NAME => $WORKTREE_PATH"
+fi
+
+# open in codium if requested
+if [[ "$FLAG_OPEN" == true ]]; then
+  echo "opening in codium..."
+  codium "$WORKTREE_PATH"
+fi

package/dist/logic/roles/mechanic/.skills/git.worktree.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = dispatcher for git worktree management
+#
+# .why  = single entry point for get|set|del subcommands
+#         enables convenient `git.worktree.sh get|set|del` interface
+#
+# .how  = routes to git.worktree.{get,set,del}.sh based on subcommand
+#
+# usage:
+#   git.worktree.sh get                     # list worktrees
+#   git.worktree.sh set <branch>            # findsert worktree
+#   git.worktree.sh set <branch> --open     # findsert + open in codium
+#   git.worktree.sh set <branch> --main     # create from origin/main
+#   git.worktree.sh del <branch>            # remove worktree
+#
+# guarantee:
+#   - dispatches to correct subcommand script
+#   - shows usage on invalid/missing subcommand
+#   - fail-fast on errors
+######################################################################
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SUBCOMMAND="${1:-}"
+
+case "$SUBCOMMAND" in
+  get|set|del)
+    shift
+    exec "$SCRIPT_DIR/git.worktree.$SUBCOMMAND.sh" "$@"
+    ;;
+  *)
+    echo "usage: git.worktree.sh <command> [args]"
+    echo ""
+    echo "commands:"
+    echo "  get              list worktrees for this repo"
+    echo "  set <branch>     findsert worktree for branch"
+    echo "  del <branch>     remove worktree for branch"
+    echo ""
+    echo "options (for set):"
+    echo "  --open           open worktree in codium after creation"
+    echo "  --main           create branch from origin/main"
+    exit 1
+    ;;
+esac

package/dist/logic/roles/mechanic/.skills/git.worktree.test.sh

@@ -0,0 +1,229 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = test suite for git worktree management scripts
+#
+# .why  = verify all worktree operations work correctly
+#
+# .how  = sets up temp git repo, exercises all commands, cleans up
+#
+# usage:
+#   ./git.worktree.test.sh
+#
+# guarantee:
+#   - creates isolated temp environment
+#   - cleans up after itself
+#   - exits 0 on success, 1 on failure
+######################################################################
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TEST_DIR=""
+TESTS_PASSED=0
+TESTS_FAILED=0
+
+# colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+NC='\033[0m' # No Color
+
+# test helper: assert condition
+assert() {
+  local description="$1"
+  local condition="$2"
+
+  if eval "$condition"; then
+    echo -e "  ${GREEN}✓${NC} $description"
+    ((TESTS_PASSED++))
+  else
+    echo -e "  ${RED}✗${NC} $description"
+    ((TESTS_FAILED++))
+  fi
+}
+
+# test helper: assert output contains
+assert_output_contains() {
+  local description="$1"
+  local output="$2"
+  local expected="$3"
+
+  if [[ "$output" == *"$expected"* ]]; then
+    echo -e "  ${GREEN}✓${NC} $description"
+    ((TESTS_PASSED++))
+  else
+    echo -e "  ${RED}✗${NC} $description"
+    echo "    expected: $expected"
+    echo "    got: $output"
+    ((TESTS_FAILED++))
+  fi
+}
+
+# setup: create temp git repo with remote
+setup() {
+  echo "setting up test environment..."
+
+  # create temp directory
+  TEST_DIR="$(mktemp -d)"
+
+  # create "remote" bare repo
+  mkdir -p "$TEST_DIR/remote.git"
+  git -C "$TEST_DIR/remote.git" init --bare -q
+
+  # create "local" repo
+  mkdir -p "$TEST_DIR/local"
+  git -C "$TEST_DIR/local" init -q
+  git -C "$TEST_DIR/local" config user.email "test@test.com"
+  git -C "$TEST_DIR/local" config user.name "Test"
+  git -C "$TEST_DIR/local" remote add origin "$TEST_DIR/remote.git"
+
+  # initial commit
+  echo "test" > "$TEST_DIR/local/README.md"
+  git -C "$TEST_DIR/local" add .
+  git -C "$TEST_DIR/local" commit -m "initial commit" -q
+
+  # push to remote (handle both main and master default branch names)
+  git -C "$TEST_DIR/local" push -u origin HEAD:main -q 2>/dev/null || true
+
+  echo "  test dir: $TEST_DIR"
+  echo ""
+}
+
+# teardown: clean up temp directory
+teardown() {
+  echo ""
+  echo "cleaning up..."
+
+  if [[ -n "$TEST_DIR" ]] && [[ -d "$TEST_DIR" ]]; then
+    rm -rf "$TEST_DIR"
+    echo "  removed: $TEST_DIR"
+  fi
+}
+
+# run tests
+run_tests() {
+  local worktree_sh="$SCRIPT_DIR/git.worktree.sh"
+
+  echo "=== test: dispatcher ==="
+
+  # test: dispatcher shows usage
+  local usage_output
+  usage_output=$("$worktree_sh" 2>&1 || true)
+  assert_output_contains "shows usage on no args" "$usage_output" "usage: git.worktree.sh"
+
+  echo ""
+  echo "=== test: get (empty) ==="
+
+  # test: get with no worktrees
+  local get_empty
+  get_empty=$(cd "$TEST_DIR/local" && "$worktree_sh" get)
+  assert_output_contains "shows no worktrees" "$get_empty" "(no worktrees)"
+
+  echo ""
+  echo "=== test: set (create) ==="
+
+  # test: set creates worktree
+  local set_output
+  set_output=$(cd "$TEST_DIR/local" && "$worktree_sh" set test/branch1)
+  assert_output_contains "creates worktree" "$set_output" "[CREATE]"
+  assert_output_contains "correct path" "$set_output" "_worktrees/local/test.branch1"
+  assert "worktree directory exists" "[[ -d '$TEST_DIR/_worktrees/local/test.branch1' ]]"
+
+  echo ""
+  echo "=== test: set (idempotent) ==="
+
+  # test: set is idempotent
+  local set_keep
+  set_keep=$(cd "$TEST_DIR/local" && "$worktree_sh" set test/branch1)
+  assert_output_contains "keeps existing worktree" "$set_keep" "[KEEP]"
+
+  echo ""
+  echo "=== test: get (with worktrees) ==="
+
+  # test: get lists worktrees
+  local get_list
+  get_list=$(cd "$TEST_DIR/local" && "$worktree_sh" get)
+  assert_output_contains "lists worktrees header" "$get_list" "worktrees for local:"
+  assert_output_contains "lists worktree entry" "$get_list" "test.branch1"
+
+  echo ""
+  echo "=== test: set (second worktree) ==="
+
+  # test: create second worktree
+  local set_second
+  set_second=$(cd "$TEST_DIR/local" && "$worktree_sh" set feature/auth)
+  assert_output_contains "creates second worktree" "$set_second" "[CREATE]"
+  assert "second worktree exists" "[[ -d '$TEST_DIR/_worktrees/local/feature.auth' ]]"
+
+  echo ""
+  echo "=== test: get from worktree ==="
+
+  # test: get from within worktree resolves same dir
+  local get_from_wt
+  get_from_wt=$(cd "$TEST_DIR/_worktrees/local/test.branch1" && "$worktree_sh" get)
+  assert_output_contains "lists from worktree" "$get_from_wt" "worktrees for local:"
+  assert_output_contains "sees both worktrees" "$get_from_wt" "feature.auth"
+
+  echo ""
+  echo "=== test: set from worktree ==="
+
+  # test: set from within worktree creates in same _worktrees dir
+  local set_from_wt
+  set_from_wt=$(cd "$TEST_DIR/_worktrees/local/test.branch1" && "$worktree_sh" set test/from-wt)
+  assert_output_contains "creates from worktree" "$set_from_wt" "[CREATE]"
+  assert "created in same _worktrees dir" "[[ -d '$TEST_DIR/_worktrees/local/test.from-wt' ]]"
+
+  echo ""
+  echo "=== test: del ==="
+
+  # test: del removes worktree
+  local del_output
+  del_output=$(cd "$TEST_DIR/local" && "$worktree_sh" del test/from-wt)
+  assert_output_contains "deletes worktree" "$del_output" "[DELETE]"
+  assert "worktree removed" "[[ ! -d '$TEST_DIR/_worktrees/local/test.from-wt' ]]"
+
+  echo ""
+  echo "=== test: del (skip nonexistent) ==="
+
+  # test: del skips nonexistent
+  local del_skip
+  del_skip=$(cd "$TEST_DIR/local" && "$worktree_sh" del nonexistent/branch)
+  assert_output_contains "skips nonexistent" "$del_skip" "[SKIP]"
+  assert_output_contains "shows not found" "$del_skip" "(not found)"
+
+  echo ""
+  echo "=== test: cleanup remaining ==="
+
+  # cleanup remaining test worktrees
+  cd "$TEST_DIR/local" && "$worktree_sh" del test/branch1 >/dev/null
+  cd "$TEST_DIR/local" && "$worktree_sh" del feature/auth >/dev/null
+
+  local final_get
+  final_get=$(cd "$TEST_DIR/local" && "$worktree_sh" get)
+  assert_output_contains "all cleaned up" "$final_get" "(no worktrees)"
+}
+
+# main
+main() {
+  echo "git.worktree.sh test suite"
+  echo "=========================="
+  echo ""
+
+  setup
+
+  # run tests (trap ensures cleanup on failure)
+  trap teardown EXIT
+  run_tests
+
+  echo ""
+  echo "=========================="
+  echo -e "passed: ${GREEN}$TESTS_PASSED${NC}"
+  echo -e "failed: ${RED}$TESTS_FAILED${NC}"
+
+  if [[ $TESTS_FAILED -gt 0 ]]; then
+    exit 1
+  fi
+
+  exit 0
+}
+
+main "$@"

package/package.json

@@ -2,7 +2,7 @@
   "name": "rhachet-roles-ehmpathy",
   "author": "ehmpathy",
   "description": "empathetic software construction roles and skills, via rhachet",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "repository": "ehmpathy/rhachet-roles-ehmpathy",
   "homepage": "https://github.com/ehmpathy/rhachet-roles-ehmpathy",
   "keywords": [