codespace-stack

#!/usr/bin/env bash

set -euo pipefail

DIRNAME="$(dirname "$(realpath "$0")")"

# shellcheck source=codespace-utils
source "$DIRNAME/codespace-utils"

# auto-detect agent environments and disable interactive prompts
test -n "${CS_NO_INTERACTIVE:-}" || {
	test -n "${CURSOR_AGENT:-}" || test -n "${CI:-}" && {
		export CS_NO_INTERACTIVE=1
	}
}

# codespace-stack: multi-repo codespace management

REPO_VALUES_INFO="\
- repo names (siblings in org directory)
- clone URLs
- objects: { \"name\": \"repo\", \"cloneURL\": \"url\" }"

STACK_HELP="\
Usage:
codespace stack [create] <branch> [-s stack_name] [-b base] [--clone|--worktree]
codespace stack init [<path>]
codespace stack extend <name>[,<name2>]...

  <branch>       branch name to create across all repos in the stack.
  <name>         stack config name from stacks.json, or repo name from org directory.

optional flags:
  -b, --base <branch>
                 base branch to create from (default: remote HEAD).
  -s, --stack <stack_name>
                 stack config name from stacks.json (default: \"default\").
  --clone        force clone mode (fresh clones for all repos).
  --worktree     force worktree mode (create worktrees from local repos).


env vars:
  CS_STACK_DEFAULT_CREATE_MODE
                 default creation mode: \"worktree\" (default) or \"clone\".
  CS_NO_INTERACTIVE
                 if set, skip interactive prompts and use defaults.
                 inferred if CURSOR_AGENT, CI, other vars are set.


config:
  stacks.json    located in \$CODESPACE_CONFIG_ROOT/<org>/stacks.json
                 format: { \"version\": \"0\", \"stacks\": { \"stack-id\": [\"repo1\", \"repo2\"] } }
                 repo values:
$(echo "$REPO_VALUES_INFO" | sed 's/^/                   /')


sub-commands:
  create <branch> [-s stack_name] [-b base] [--clone|--worktree]
                  create a new stack with repos from a stack configuration.
                  \"create\" is implied if omitted.

  post-create [-s stack_name]
                  run the stack post-create script in an existing stack.
                  must be run from within a stack directory (or child).
                  [-s stack_name] specifies which stack config to use (default: \"default\").

  extend <name>[,<name2>]...
                  extend current stack with repos from stack configs or repo names.
                  first checks stacks.json, then falls back to repos in <org> directory.
                  must be run from within an existing stack directory (or child).
                  uses the same creation mode (clone/worktree) as existing repos.

  init [<path>]   create a stacks.json configuration file in CODESPACE_CONFIG_ROOT.
				  <path> is the directory where stacks will be held.
                  if <path> is provided, uses that directory.
                  otherwise, prompts to select current or parent directory.


examples:
  codespace stack create feature1              # create stack \"feature1\",
                                               # add repos defined in \"default\" stack config in stacks.json,
                                               # checkout each repo into \"feature1\" branch.

  codespace stack create feature1 -s config2    # create stack from \"config2\" config in stacks.json.
  codespace stack create feature1 -b develop   # base the stack off of the \"develop\" branch,
                                               # instead of repository's default branch.
  codespace stack create feature1 --clone      # create clones, instead of worktrees.

  codespace stack post-create            # run stack post-create script (uses \"default\" config)
  codespace stack post-create -s full    # run post-create using \"full\" stack config

  codespace stack extend be              # add repos from \"be\" stack config
  codespace stack extend be,infra        # add repos from \"be\" and \"infra\" stack configs
  codespace stack extend backend         # add \"backend\" repo directly

  codespace stack init                   # create stacks.json config file (interactive)
  codespace stack init ~/projects/myorg  # create config for stacks held in specified path
"

cs_stack_main() {
	# handle help
	case "${1:-}" in
		-h|--help)
			echo "$STACK_HELP"
			exit 0
			;;
		"")
			>&2 echo "$STACK_HELP"
			exit 1
			;;
	esac

	# dispatch subcommands
	cmd="$1"
	shift

	case "$cmd" in
		create)
			cs_stack_create "$@"
			;;
		init)
			cs_stack_init "$@"
			;;
		init-repo)
			# internal subcommand used by cs_stack_create for parallel repo init
			cs_stack_init_repo "$@"
			;;
		extend)
			cs_stack_extend "$@"
			;;
		post-create)
			cs_stack_post_create "$@"
			;;
		*)
			# implied create
			cs_stack_create "$cmd" "$@"
			;;
	esac
}

# Parse and validate create arguments
# Sets globals: branch, stack_name, create_mode, base_branch
cs_stack_create_parse_args() {
	branch=""
	stack_name="default"
	base_branch=""
	local mode_flag=""

	while [ $# -gt 0 ]; do
		case "$1" in
			-s|--stack)
				shift
				stack_name="${1:-}"
				test -n "$stack_name" || {
					>&2 echo "err: -s requires a stack name"
					exit 1
				}
				;;
			-b|--base)
				shift
				base_branch="${1:-}"
				test -n "$base_branch" || {
					>&2 echo "err: -b requires a base branch"
					exit 1
				}
				;;
			--clone)
				mode_flag="clone"
				;;
			--worktree)
				mode_flag="worktree"
				;;
			-*)
				>&2 echo "err: unknown option: $1"
				exit 1
				;;
			*)
				if [ -z "$branch" ]; then
					branch="$1"
				else
					>&2 echo "err: unexpected argument: $1"
					exit 1
				fi
				;;
		esac
		shift
	done

	test -n "$branch" || {
		>&2 echo "err: <branch> is required"
		>&2 echo "usage: codespace stack [create] <branch> [-s stack_name]"
		exit 1
	}

	# determine creation mode (priority: flag > env > default)
	if [ -n "$mode_flag" ]; then
		create_mode="$mode_flag"
	elif [ -n "${CS_STACK_DEFAULT_CREATE_MODE:-}" ]; then
		create_mode="$CS_STACK_DEFAULT_CREATE_MODE"
	else
		create_mode="worktree"
	fi
}

# Setup stack directory structure
# Uses globals: branch, org_dir
# Sets globals: stack_dir, logs_dir
cs_stack_create_setup_dirs() {
	stack_dir="$org_dir/stack_$(cs_cleanpath "$branch")"
	if [ -d "$stack_dir" ]; then
		>&2 echo "err: stack directory already exists: $stack_dir"
		exit 1
	fi
	mkdir -p "$stack_dir"

	logs_dir="$stack_dir/.stack-init-logs"
	mkdir -p "$logs_dir"
}

# Setup tmux session if available
# Uses globals: branch, logs_dir
# Sets globals: use_tmux, tmux_session
cs_stack_create_setup_tmux() {
	use_tmux=""
	tmux_session=""
	if [ -z "${CS_NO_INTERACTIVE:-}" ] && command -v tmux >/dev/null 2>&1; then
		use_tmux=1
		tmux_session="stack-init-$(cs_cleanpath "$branch")"
		# kill existing session if present (e.g. from previous extend that was interrupted)
		tmux kill-session -t "$tmux_session" 2>/dev/null || true
		# create session with placeholder window (will be killed after repo windows are created)
		tmux new-session -d -s "$tmux_session" -n "_placeholder"
		# increase scrollback buffer so user can see all init logs
		tmux set-option -t "$tmux_session" history-limit 50000
		# enable mouse mode for terminal scrolling
		tmux set-option -t "$tmux_session" mouse on
	fi
}

# Pre-parse all repos into arrays
# Args: $1 = repos (newline-separated JSON entries)
# Uses globals: stack_dir, org_dir
# Sets globals: repo_names[], repo_clone_urls[], repo_dests[], repo_base_repos[]
cs_stack_create_prepare_repos() {
	local repos="$1"

	repo_names=()
	repo_clone_urls=()
	repo_dests=()
	repo_base_repos=()

	while IFS= read -r repo_entry; do
		test -n "$repo_entry" || continue

		cs_stack_parse_repo_entry "$repo_entry"
		# repo_name and clone_url are set by cs_stack_parse_repo_entry

		local local_repo_name="$repo_name"
		local local_clone_url="$clone_url"
		local repo_dest="$stack_dir/$local_repo_name"
		local base_repo="$org_dir/$local_repo_name"

		# Resolve clone URL if needed (repo doesn't exist locally and no URL provided)
		if [ -z "$local_clone_url" ] && [ ! -d "$base_repo/.git" ]; then
			local_clone_url="$(cs_infer_clone_url "$local_repo_name" "$org_dir")" || {
				>&2 echo "err: repo '$local_repo_name' not found locally and couldn't infer clone URL"
				>&2 echo "options:"
				>&2 echo "  a) clone the repo: git clone <url> $base_repo"
				>&2 echo "  b) add clone URL to stacks.json"
				exit 1
			}
		fi

		repo_names+=("$local_repo_name")
		repo_clone_urls+=("$local_clone_url")
		repo_dests+=("$repo_dest")
		repo_base_repos+=("$base_repo")
	done <<< "$repos"
}

# Spawn parallel repo init jobs
# Uses globals: create_mode, repo_names[], repo_clone_urls[], repo_dests[],
#               repo_base_repos[], logs_dir, use_tmux, tmux_session, branch, base_branch
# Sets globals: repo_pids[]
cs_stack_create_spawn_jobs() {
	>&2 echo "==> initializing repos (${#repo_names[@]} repos, mode: $create_mode)"
	>&2 echo "  logs: \"$logs_dir\""
	if [ -n "$use_tmux" ]; then
		>&2 echo "  preview with:"
		echo "  tmux attach -t $tmux_session"
	fi

	repo_pids=()
	for i in "${!repo_names[@]}"; do
		local r_name="${repo_names[$i]}"
		local r_clone_url="${repo_clone_urls[$i]}"
		local r_dest="${repo_dests[$i]}"
		local r_base="${repo_base_repos[$i]}"
		local log_file="$logs_dir/$r_name.log"

		if [ -n "$use_tmux" ]; then
			# tmux mode: create window with shell, then send init command
			# after init, open log in less with mouse support for scrolling (strip ^M with col -b)
			tmux new-window -t "$tmux_session" -n "$r_name"
			tmux send-keys -t "$tmux_session:$r_name" \
				"'$DIRNAME/codespace-stack' init-repo '$create_mode' '$r_name' '$r_clone_url' '$r_dest' '$r_base' '$branch' '$base_branch' 2>&1 | tee '$log_file' && { echo '=== [$r_name] Init complete. Press q to exit, or scroll with mouse ==='; col -b < '$log_file' | less -R --mouse +G; }" Enter
			# kill placeholder window after first real window is created
			tmux kill-window -t "$tmux_session:_placeholder" 2>/dev/null || true
		else
			# no tmux: background job with file logging
			(
				"$DIRNAME/codespace-stack" init-repo "$create_mode" "$r_name" "$r_clone_url" "$r_dest" "$r_base" "$branch" "$base_branch"
			) >"$log_file" 2>&1 &
			repo_pids+=($!)
		fi
	done
}

# Spawn stack-level post-create script (runs in parallel with repo init jobs)
# Uses globals: stacks_json, stack_name, branch, stack_dir, create_mode, org_dir,
#               repo_names[], logs_dir, use_tmux, tmux_session
# Sets globals: stack_post_create_spawned, stack_post_create_pid
cs_stack_spawn_stack_post_create() {
	stack_post_create_spawned=""
	stack_post_create_pid=""

	# skip if stacks_json is not set (e.g. extend without config)
	if [ -z "${stacks_json:-}" ]; then
		return 0
	fi

	local script_path
	script_path="$(cs_stack_get_post_create_config "$stack_name" "$stacks_json")"
	[ -n "$script_path" ] || return 0
	[ -f "$script_path" ] || { >&2 echo "  note: stack post-create script not found: $script_path"; return 0; }
	[ -x "$script_path" ] || { >&2 echo "  warn: stack post-create not executable: $script_path"; return 0; }

	local repos_csv config_dir log_file
	repos_csv="$(IFS=,; echo "${repo_names[*]}")"
	config_dir="$(dirname "$stacks_json")"
	log_file="$logs_dir/stack-post-create.log"

	>&2 echo "==> running stack post-create script"
	>&2 echo "  script: $script_path"

	if [ -n "$use_tmux" ]; then
		tmux new-window -t "$tmux_session" -n "stack-post-create"
		tmux send-keys -t "$tmux_session:stack-post-create" \
			"{ STACK_NAME='$stack_name' STACK_BRANCH='$branch' STACK_ROOT='$stack_dir' STACK_CONFIG_ROOT='$config_dir' STACK_REPOS='$repos_csv' STACK_CREATE_MODE='$create_mode' STACK_ORG_DIR='$org_dir' '$script_path' && echo '=== [stack-post-create] Done ===' || echo 'STACK_POST_CREATE_FAILED'; } 2>&1 | tee '$log_file'; echo 'Press q to exit, or scroll with mouse'; col -b < '$log_file' | less -R --mouse +G" Enter
	else
		(
			STACK_NAME="$stack_name" STACK_BRANCH="$branch" STACK_ROOT="$stack_dir" \
			STACK_CONFIG_ROOT="$config_dir" STACK_REPOS="$repos_csv" \
			STACK_CREATE_MODE="$create_mode" STACK_ORG_DIR="$org_dir" \
			"$script_path" && echo "=== [stack-post-create] Done ===" || echo "STACK_POST_CREATE_FAILED"
		) >"$log_file" 2>&1 &
		stack_post_create_pid=$!
	fi

	stack_post_create_spawned=1
}

# Wait for jobs and print summary
# Args: $1 = mode ("create" or "extend")
# Uses globals: use_tmux, tmux_session, repo_names[], logs_dir, repo_pids[], stack_dir,
#               stack_post_create_spawned, stack_post_create_pid
cs_stack_create_wait_and_summarize() {
	local mode="${1:-create}"
	local failures=()
	local stack_post_create_failed=""

	if [ -n "$use_tmux" ]; then
		# build list of jobs to wait for
		local wait_jobs=("${repo_names[@]}")
		if [ -n "${stack_post_create_spawned:-}" ]; then
			wait_jobs+=("stack-post-create")
		fi

		cs_stack_tmux_wait "$logs_dir" "${wait_jobs[@]}"

		# check logs for failures
		for i in "${!repo_names[@]}"; do
			local r_name="${repo_names[$i]}"
			local log_file="$logs_dir/$r_name.log"
			if [ -f "$log_file" ] && grep -qE "CLONE_FAILED|POST_CREATE_FAILED" "$log_file"; then
				failures+=("$r_name")
			fi
		done

		# check stack post-create log
		if [ -n "${stack_post_create_spawned:-}" ]; then
			local stack_log="$logs_dir/stack-post-create.log"
			if [ -f "$stack_log" ] && grep -q "STACK_POST_CREATE_FAILED" "$stack_log"; then
				stack_post_create_failed=1
			fi
		fi
	else
		for i in "${!repo_pids[@]}"; do
			local pid="${repo_pids[$i]}"
			local r_name="${repo_names[$i]}"
			if ! wait "$pid"; then
				failures+=("$r_name")
			fi
		done

		# wait for stack post-create job
		if [ -n "${stack_post_create_spawned:-}" ] && [ -n "${stack_post_create_pid:-}" ]; then
			if ! wait "$stack_post_create_pid"; then
				stack_post_create_failed=1
			fi
		fi
	fi

	local verb
	if [ "$mode" = "extend" ]; then
		verb="extended"
	else
		verb="created"
	fi

	echo
	if [ ${#failures[@]} -gt 0 ] || [ -n "$stack_post_create_failed" ]; then
		>&2 echo "==> stack $verb with errors:"
		if [ ${#failures[@]} -gt 0 ]; then
			>&2 echo "  failed repos: ${failures[*]}"
		fi
		if [ -n "$stack_post_create_failed" ]; then
			>&2 echo "  stack post-create script failed"
		fi
		>&2 echo "  logs: $logs_dir"
		if [ -n "$use_tmux" ]; then
			>&2 echo "    tmux session: tmux attach -t $tmux_session"
		fi
	else
		>&2 echo "==> stack $verb successfully"
		# clean up logs on success (unless DEBUG is set)
		if [ -z "${DEBUG:-}" ]; then
			rm -rf "$logs_dir"
		else
			>&2 echo "  logs: $logs_dir"
		fi
		# tmux session is kept alive for user to attach and inspect
	fi

	# print summary
	if [ "$mode" = "extend" ]; then
		echo "  $stack_dir"
		for r_name in "${repo_names[@]}"; do
			echo "  + $r_name"
		done
	else
		echo "  $stack_dir"
	fi
	echo ""
}

# Open editor for the stack
# Uses globals: stack_dir
cs_stack_create_open_editor() {
	>&2 echo "==> opening editor"
	GUI_EDITOR="${GUI_EDITOR:-$EDITOR}"
	if [ -n "$GUI_EDITOR" ]; then
		(unset GIT_DIR GIT_WORK_TREE; "$GUI_EDITOR" --new-window "$stack_dir") &
	else
		>&2 echo "warn: neither \$GUI_EDITOR nor \$EDITOR env var set, cannot open stack with editor"
	fi
}

cs_stack_create() {
	cs_stack_create_parse_args "$@"

	# find stacks.json config and org directory
	# cs_stack_find_config outputs two lines: config_path and org_dir
	config_output="$(cs_stack_find_config)"
	stacks_json="$(echo "$config_output" | head -n1)"
	org_dir="$(echo "$config_output" | tail -n1)"

	# get repos for the stack
	repos="$(cs_stack_get_repos "$stack_name" "$stacks_json")"
	test -n "$repos" || {
		>&2 echo "err: stack '$stack_name' not found or empty in $stacks_json"
		exit 1
	}

	cs_stack_create_setup_dirs
	cs_stack_create_setup_tmux
	cs_stack_create_prepare_repos "$repos"
	cs_stack_create_open_editor
	cs_stack_create_spawn_jobs
	cs_stack_spawn_stack_post_create
	cs_stack_create_wait_and_summarize "create"
}

# extend an existing stack with repos from other stack configurations or repo names
cs_stack_extend() {
	# parse arguments
	local extend_args="${1:-}"
	test -n "$extend_args" || {
		>&2 echo "err: <stack_name|repo_name> is required"
		>&2 echo "usage: codespace stack extend <stack_name>[,<stack_name2>]..."
		>&2 echo "  accepts stack config names from stacks.json, or repo names from org directory"
		exit 1
	}

	# detect current stack
	local detect_output
	detect_output="$(cs_stack_detect_current)" || {
		>&2 echo "err: not inside a stack directory"
		>&2 echo "hint: run this command from within a stack_* directory or a repo inside one"
		exit 1
	}

	stack_dir="$(echo "$detect_output" | sed -n '1p')"
	branch="$(echo "$detect_output" | sed -n '2p')"
	org_dir="$(echo "$detect_output" | sed -n '3p')"

	>&2 echo "==> extending stack: $stack_dir"
	>&2 echo "  branch: $branch"

	# detect creation mode from existing repos
	create_mode="$(cs_stack_detect_mode "$stack_dir")"
	>&2 echo "  mode: $create_mode (auto-detected from existing repos)"

	# base_branch not used for extend (uses default branch of each repo)
	base_branch=""

	# find stacks.json config (optional for repo-name mode)
	# note: stacks_json is global so cs_stack_spawn_stack_post_create can access it
	stacks_json=""
	if [ -n "${CODESPACE_CONFIG_ROOT:-}" ]; then
		local rel_path
		rel_path="$(realpath "$org_dir" --relative-to="$HOME" 2>/dev/null)" || rel_path="$org_dir"
		stacks_json="$CODESPACE_CONFIG_ROOT/$rel_path/stacks.json"
		test -f "$stacks_json" || stacks_json=""
	fi

	# stack_name for extend uses a special marker (only global post-create settings apply)
	stack_name="_extend"

	# get list of existing repos/directories in the stack
	local existing_repos=()
	for repo_dir in "$stack_dir"/*; do
		test -d "$repo_dir" || continue
		existing_repos+=("$(basename "$repo_dir")")
	done

	# collect repos from all specified stack configs or repo names
	local all_new_repos=""
	IFS=',' read -ra arg_names <<< "$extend_args"
	for arg_name in "${arg_names[@]}"; do
		# trim whitespace
		arg_name="$(echo "$arg_name" | xargs)"
		test -n "$arg_name" || continue

		local repos=""
		local source_type=""

		# first, try as stack config name
		if [ -n "$stacks_json" ]; then
			repos="$(cs_stack_get_repos "$arg_name" "$stacks_json" 2>/dev/null)" && source_type="stack"
		fi

		# if not found as stack config, try as repo name in org directory
		if [ -z "$source_type" ]; then
			if [ -d "$org_dir/$arg_name/.git" ]; then
				# repo exists locally - create a simple repo entry
				repos="\"$arg_name\""
				source_type="repo"
			else
				# check if we can infer clone URL
				local inferred_url
				if inferred_url="$(cs_infer_clone_url "$arg_name" "$org_dir" 2>/dev/null)"; then
					repos="{ \"name\": \"$arg_name\", \"cloneURL\": \"$inferred_url\" }"
					source_type="repo (inferred)"
				else
					>&2 echo "err: '$arg_name' not found as stack config or repo in $org_dir"
					exit 1
				fi
			fi
		fi

		>&2 echo "  adding from $source_type: $arg_name"

		# filter out repos that already exist
		while IFS= read -r repo_entry; do
			test -n "$repo_entry" || continue

			cs_stack_parse_repo_entry "$repo_entry"
			# repo_name is set by cs_stack_parse_repo_entry

			# check if already exists
			local exists=""
			for existing in "${existing_repos[@]}"; do
				if [ "$existing" = "$repo_name" ]; then
					exists=1
					break
				fi
			done

			if [ -n "$exists" ]; then
				>&2 echo "    skipping '$repo_name' (already in stack)"
			else
				if [ -z "$all_new_repos" ]; then
					all_new_repos="$repo_entry"
				else
					all_new_repos="$all_new_repos"$'\n'"$repo_entry"
				fi
				# add to existing list to avoid duplicates across configs
				existing_repos+=("$repo_name")
			fi
		done <<< "$repos"
	done

	# check if there are any new repos to add
	test -n "$all_new_repos" || {
		>&2 echo "==> no new repos to add (all already in stack)"
		exit 0
	}

	# setup logs directory
	logs_dir="$stack_dir/.stack-extend-logs"
	mkdir -p "$logs_dir"

	# setup tmux if available
	cs_stack_create_setup_tmux

	# prepare and spawn jobs for new repos
	cs_stack_create_prepare_repos "$all_new_repos"
	cs_stack_create_spawn_jobs
	cs_stack_spawn_stack_post_create
	cs_stack_create_wait_and_summarize "extend"
}

# run stack post-create script in an existing stack
# Uses cs_stack_spawn_stack_post_create internally to avoid code duplication
cs_stack_post_create() {
	stack_name="default"
	while [ $# -gt 0 ]; do
		case "$1" in
			-s|--stack) shift; stack_name="${1:?err: -s requires a stack name}" ;;
			-*) >&2 echo "err: unknown option: $1"; exit 1 ;;
			*) >&2 echo "err: unexpected argument: $1"; exit 1 ;;
		esac
		shift
	done

	# detect current stack
	local detect_output
	detect_output="$(cs_stack_detect_current)" || {
		>&2 echo "err: not inside a stack directory"
		exit 1
	}
	stack_dir="$(echo "$detect_output" | sed -n '1p')"
	branch="$(echo "$detect_output" | sed -n '2p')"
	org_dir="$(echo "$detect_output" | sed -n '3p')"

	# find stacks.json
	stacks_json=""
	if [ -n "${CODESPACE_CONFIG_ROOT:-}" ]; then
		local rel_path
		rel_path="$(realpath "$org_dir" --relative-to="$HOME" 2>/dev/null)" || rel_path="$org_dir"
		stacks_json="$CODESPACE_CONFIG_ROOT/$rel_path/stacks.json"
		[ -f "$stacks_json" ] || stacks_json=""
	fi
	[ -n "$stacks_json" ] || { >&2 echo "err: stacks.json not found"; exit 1; }

	# set up globals for cs_stack_spawn_stack_post_create
	repo_names=()
	for d in "$stack_dir"/*; do [ -d "$d/.git" ] && repo_names+=("$(basename "$d")"); done
	create_mode="$(cs_stack_detect_mode "$stack_dir")"
	logs_dir="$(mktemp -d -t stack-post-create.XXXXXX)"

	# set up tmux and run
	cs_stack_create_setup_tmux
	cs_stack_spawn_stack_post_create

	# wait for completion
	if [ -n "${stack_post_create_spawned:-}" ]; then
		if [ -n "$use_tmux" ]; then
			cs_stack_tmux_wait "$logs_dir" "stack-post-create"
			# check result
			if grep -q "STACK_POST_CREATE_FAILED" "$logs_dir/stack-post-create.log" 2>/dev/null; then
				>&2 echo "==> stack post-create failed"
				>&2 echo "  logs: $logs_dir"
				exit 1
			fi
		else
			if ! wait "$stack_post_create_pid"; then
				>&2 echo "==> stack post-create failed"
				>&2 echo "  logs: $logs_dir"
				exit 1
			fi
		fi
		>&2 echo "==> stack post-create completed"
		[ -z "${DEBUG:-}" ] && rm -rf "$logs_dir"
	fi
}

# Wait for tmux repo init jobs to complete by polling log files
# Args: logs_dir, repo_names...
cs_stack_tmux_wait() {
	local wait_logs_dir="$1"
	shift

	# poll until all jobs have completed (check for Done or failure markers in logs)
	while true; do
		remaining=0
		for r_name in "$@"; do
			local log_file="$wait_logs_dir/$r_name.log"
			# check if log file exists and contains completion marker
			# (pattern is lenient to handle buffering/whitespace variations)
			if [ -f "$log_file" ]; then
				if grep -qE "\[$r_name\] Done ===|CLONE_FAILED|POST_CREATE_FAILED|STACK_POST_CREATE_FAILED" "$log_file"; then
					continue  # this job is done
				fi
			fi
			remaining=$((remaining + 1))
		done
		[ "$remaining" -eq 0 ] && break
		sleep 1
	done
}

# Find stacks.json config by walking up from org_dir
# Outputs two lines:
#   Line 1: config file path
#   Line 2: org directory where config was found (use this for stack creation)
cs_stack_find_config() {
	test -n "${CODESPACE_CONFIG_ROOT:-}" || {
		>&2 echo "err: env var '\$CODESPACE_CONFIG_ROOT' not set"
		exit 1
	}

	start_dir="$(cs_stack_get_org_dir)"
	current_dir="$start_dir"
	levels_up=0

	while true; do
		rel_path="$(realpath "$current_dir" --relative-to="$HOME" 2>/dev/null)" || rel_path="$current_dir"
		config_path="$CODESPACE_CONFIG_ROOT/$rel_path/stacks.json"

		if [ -f "$config_path" ]; then
			# if we went more than 1 level up, ask for confirmation
			if [ "$levels_up" -gt 1 ]; then
				if [ -n "${CS_NO_INTERACTIVE:-}" ]; then
					>&2 echo "found stacks.json $levels_up levels up, stack will be created in: $current_dir (auto-accepting, CS_NO_INTERACTIVE set)"
				else
					>&2 printf "found stacks.json $levels_up levels up, stack will be created in: $current_dir. use? [y/n] "
					read -r answer </dev/tty
					case "$answer" in
						y|Y|yes|Yes) ;;
						*)
							>&2 echo "aborted"
							exit 1
							;;
					esac
				fi
			fi
			# output config path and the matched org directory
			echo "$config_path"
			echo "$current_dir"
			return 0
		fi

		# check if we've reached home or root
		if [ "$current_dir" = "$HOME" ] || [ "$current_dir" = "/" ]; then
			break
		fi

		current_dir="$(dirname "$current_dir")"
		levels_up=$((levels_up + 1))
	done

	>&2 echo "err: stacks.json not found"
	>&2 echo "searched from: $start_dir"
	>&2 echo "expected location: \$CODESPACE_CONFIG_ROOT/<org>/stacks.json"
	>&2 echo "hint: run 'codespace stack init' to create one"
	exit 1
}

cs_stack_init() {
	test -n "${CODESPACE_CONFIG_ROOT:-}" || {
		>&2 echo "err: env var '\$CODESPACE_CONFIG_ROOT' not set"
		exit 1
	}

	# check if a config already exists (possibly at a higher level)
	if config_output="$(cs_stack_find_config 2>/dev/null)"; then
		existing_config="$(echo "$config_output" | head -n1)"
		existing_org_dir="$(echo "$config_output" | tail -n1)"
		>&2 echo "stacks.json already exists at:"
		echo "$existing_config"
		>&2 echo "(org directory: $existing_org_dir)"
		exit 0
	fi

	# determine org directory
	local org_dir=""

	if [ -n "${1:-}" ]; then
		# path provided as argument
		org_dir="$(realpath "$1" 2>/dev/null)" || {
			>&2 echo "err: invalid path: $1"
			exit 1
		}
		if [ ! -d "$org_dir" ]; then
			>&2 echo "err: not a directory: $org_dir"
			exit 1
		fi
	elif [ -z "${CS_NO_INTERACTIVE:-}" ]; then
		# interactive mode: offer choices
		local current_dir parent_dir
		current_dir="$(pwd)"
		parent_dir="$(dirname "$current_dir")"

		# check if we're inside a git repo (parent might be org level)
		local in_git_repo=""
		if git rev-parse --git-dir >/dev/null 2>&1; then
			in_git_repo=1
		fi

		>&2 echo "Select directory where stacks will be held:"
		>&2 echo ""
		>&2 echo "  1) $current_dir"
		if [ -n "$in_git_repo" ]; then
			>&2 echo "  2) $parent_dir  (parent - you're inside a git repo)"
		else
			>&2 echo "  2) $parent_dir  (parent)"
		fi
		>&2 echo "  0) Exit (use 'codespace stack init <path>' to specify directly)"
		>&2 echo ""
		>&2 printf "Choice [1/2/0]: "
		read -r choice </dev/tty
		case "$choice" in
			1) org_dir="$current_dir" ;;
			2) org_dir="$parent_dir" ;;
			0|"")
				>&2 echo "aborted"
				exit 1
				;;
			*)
				>&2 echo "err: invalid choice: $choice"
				exit 1
				;;
		esac
	else
		# non-interactive mode: use current directory
		org_dir="$(pwd)"
	fi

	local org_name rel_path config_dir config_path
	org_name="$(basename "$org_dir")"
	rel_path="$(realpath "$org_dir" --relative-to="$HOME" 2>/dev/null)" || rel_path="$org_dir"
	config_dir="$CODESPACE_CONFIG_ROOT/$rel_path"
	config_path="$config_dir/stacks.json"

	>&2 echo ""
	>&2 echo "Creating configuration for org \"$org_name\""
	>&2 echo "  org directory: $org_dir"
	>&2 echo "  config path:   $config_path"

	# discover repos in org directory for template
	repos_json="$(cs_stack_discover_repos "$org_dir")"

	mkdir -p "$config_dir"

	# create template stacks.json
	cat > "$config_path" << EOF
{
    "version": "0",
    "enableGlobalPostCreateScript": true,
    "stacks": {
        "default": $repos_json
    }
}
EOF

	# create sample stack-post-create.sh script
	local script_path="$config_dir/stack-post-create.sh"
	cat > "$script_path" << 'EOF'
#!/bin/bash
# stack-post-create.sh - runs after stack creation (in parallel with repo post-create scripts)
#
# Available environment variables:
#   STACK_NAME        - stack config name (e.g., "default")
#   STACK_BRANCH      - branch name for the stack
#   STACK_ROOT        - absolute path to stack directory
#   STACK_CONFIG_ROOT - config directory (where stacks.json lives)
#   STACK_REPOS       - comma-separated list of repo names
#   STACK_CREATE_MODE - "worktree" or "clone"
#   STACK_ORG_DIR     - parent org directory

echo "=== Stack post-create: $STACK_NAME ==="
echo "Branch: $STACK_BRANCH"
echo "Repos: $STACK_REPOS"
echo "Dir: $STACK_ROOT"

# Example: link file from config to stack root
# ln -s "$STACK_CONFIG_ROOT/AGENTS.md" "$STACK_ROOT/AGENTS.md"

# Example: create shared .env file across repos
# for repo in ${STACK_REPOS//,/ }; do
#     cp "$STACK_ORG_DIR/templates/.env.template" "$STACK_ROOT/$repo/.env"
# done

# Example: create stack-level config
# echo "STACK_BRANCH=$STACK_BRANCH" > "$STACK_ROOT/.stack-env"
EOF
	chmod +x "$script_path"

	info="\
edit the file to configure your stacks:
  - \"default\" stack contains discovered repos from: $org_dir
  - add more stacks as needed
  - repo values can be:
$(echo "$REPO_VALUES_INFO" | sed 's/^/      /')
  - set \"enableGlobalPostCreateScript\": false to disable stack-post-create.sh

created:
  $config_path
  $script_path\
"

	echo "$info"
}

# Discover repos in org directory and return as JSON array
cs_stack_discover_repos() {
	org_dir="$1"
	repos=""
	indent="            "  # 12 spaces for array items

	for dir in "$org_dir"/*; do
		test -d "$dir/.git" || continue
		repo_name="$(basename "$dir")"
		clone_url="$(git -C "$dir" remote get-url origin 2>/dev/null)" || clone_url=""

		if [ -n "$clone_url" ]; then
			entry="{ \"name\": \"$repo_name\", \"cloneURL\": \"$clone_url\" }"
		else
			entry="\"$repo_name\""
		fi

		if [ -z "$repos" ]; then
			repos="$entry"
		else
			repos="$repos,
$indent$entry"
		fi
	done

	if [ -z "$repos" ]; then
		echo '[
            { "name": "repo1", "cloneURL": "git@github.com:org/repo1.git" },
            { "name": "repo2", "cloneURL": "git@github.com:org/repo2.git" }
        ]'
	else
		echo "[
$indent$repos
        ]"
	fi
}

cs_stack_get_org_dir() {
	# if inside a git repo, go to parent (org level)
	# otherwise use current directory
	if git rev-parse --git-dir >/dev/null 2>&1; then
		# use cs_abs_path_base_repo to properly resolve through worktrees
		repo_root="$(cs_abs_path_base_repo)"
		dirname "$repo_root"
	else
		pwd
	fi
}

# detect if we're inside a stack directory by walking up the tree
# outputs three lines:
#   line 1: stack directory path
#   line 2: branch name (extracted from stack_<branch> pattern)
#   line 3: org directory (parent of stack)
# returns non-zero if not inside a stack
cs_stack_detect_current() {
	local current_dir
	current_dir="$(pwd)"

	while true; do
		local dir_name
		dir_name="$(basename "$current_dir")"

		# check if directory name matches stack_* pattern
		if [[ "$dir_name" == stack_* ]]; then
			local stack_dir="$current_dir"
			local org_dir
			org_dir="$(dirname "$current_dir")"
			# extract branch name by removing "stack_" prefix
			local branch="${dir_name#stack_}"

			echo "$stack_dir"
			echo "$branch"
			echo "$org_dir"
			return 0
		fi

		# check if we've reached root
		if [ "$current_dir" = "/" ]; then
			break
		fi

		current_dir="$(dirname "$current_dir")"
	done

	return 1
}

# detect creation mode of existing stack by checking for clone markers
# outputs: "clone" or "worktree"
cs_stack_detect_mode() {
	local stack_dir="$1"

	# check each repo in the stack for clone marker
	for repo_dir in "$stack_dir"/*; do
		test -d "$repo_dir/.git" || continue
		if [ -f "$repo_dir/.git/CODESPACE_IS_CLONE" ]; then
			echo "clone"
			return 0
		fi
	done

	# default to worktree if no clone markers found
	echo "worktree"
}

cs_stack_get_repos() {
	local stack_name="$1"
	local stacks_json="$2"

	# check if jq is available
	command -v jq >/dev/null 2>&1 || {
		>&2 echo "err: 'jq' is required to parse stacks.json"
		>&2 echo "install it with: brew install jq (macOS) or apt install jq (Linux)"
		exit 1
	}

	# extract repos array for the given stack
	# stack value can be either an array directly, or an object with "repos" key
	# each repo entry is output on a separate line as JSON
	local stack_value
	stack_value="$(jq -c --arg name "$stack_name" '.stacks[$name]' "$stacks_json" 2>/dev/null)" || {
		>&2 echo "err: failed to parse stacks.json"
		exit 1
	}

	if [ "$stack_value" = "null" ] || [ -z "$stack_value" ]; then
		>&2 echo "err: stack '$stack_name' not found in $stacks_json"
		exit 1
	fi

	# check if it's an array or object
	local value_type
	value_type="$(echo "$stack_value" | jq -r 'type')"

	if [ "$value_type" = "array" ]; then
		# direct array of repos
		echo "$stack_value" | jq -c '.[]'
	elif [ "$value_type" = "object" ]; then
		# object with "repos" key
		echo "$stack_value" | jq -c '.repos[]' 2>/dev/null || {
			>&2 echo "err: stack '$stack_name' is an object but missing 'repos' array"
			exit 1
		}
	else
		>&2 echo "err: stack '$stack_name' has invalid type: $value_type (expected array or object)"
		exit 1
	fi
}

# Get post-create script configuration for a stack
# Args: stack_name, stacks_json
# Outputs: script path to run (empty if disabled)
# Uses: stacks_json path to determine config directory
cs_stack_get_post_create_config() {
	local stack_name="$1"
	local stacks_json="$2"
	local config_dir
	config_dir="$(dirname "$stacks_json")"

	# get top-level enableGlobalPostCreateScript (default: true)
	local global_enabled
	global_enabled="$(jq -r '.enableGlobalPostCreateScript // true' "$stacks_json")"

	# get stack-specific settings
	local stack_value
	stack_value="$(jq -c --arg name "$stack_name" '.stacks[$name]' "$stacks_json" 2>/dev/null)"

	local stack_enabled=""
	local custom_script=""

	# only objects can have per-stack settings
	if [ -n "$stack_value" ] && [ "$stack_value" != "null" ]; then
		local value_type
		value_type="$(echo "$stack_value" | jq -r 'type')"
		if [ "$value_type" = "object" ]; then
			stack_enabled="$(echo "$stack_value" | jq -r '.enableGlobalPostCreateScript // empty')"
			custom_script="$(echo "$stack_value" | jq -r '.customPostCreateScript // empty')"
		fi
	fi

	# Resolution order:
	# 1. If stack has customPostCreateScript -> use that script
	# 2. Else if stack has enableGlobalPostCreateScript: false -> skip
	# 3. Else if top-level enableGlobalPostCreateScript: false -> skip
	# 4. Else -> use stack-post-create.sh

	if [ -n "$custom_script" ]; then
		# custom script path (relative to stacks.json)
		echo "$config_dir/$custom_script"
		return 0
	fi

	if [ "$stack_enabled" = "false" ]; then
		# explicitly disabled for this stack
		return 0
	fi

	if [ "$global_enabled" = "false" ]; then
		# globally disabled
		return 0
	fi

	# use default global script
	echo "$config_dir/stack-post-create.sh"
}

# Parse a repo entry from stacks.json, setting globals: repo_name, clone_url
# Entry can be: string (repo name or URL) or object {"name": "...", "cloneURL": "..."}
cs_stack_parse_repo_entry() {
	entry="$1"

	# reset globals
	repo_name=""
	clone_url=""

	if echo "$entry" | grep -q '^{'; then
		# JSON object: {"name": "repo", "cloneURL": "url"}
		repo_name="$(echo "$entry" | jq -r '.name')"
		clone_url="$(echo "$entry" | jq -r '.cloneURL // empty')"
	else
		# String value
		value="$(echo "$entry" | jq -r '.')"
		if echo "$value" | grep -qE '^(https?://|git@|ssh://)'; then
			clone_url="$value"
			repo_name="$(cs_repo_name_from_url "$value")"
		else
			repo_name="$value"
		fi
	fi

	test -n "$repo_name" || {
		>&2 echo "err: could not determine repo name from entry: $entry"
		exit 1
	}
}

# init a single repo for stack (clone/worktree + post-create)
cs_stack_init_repo() {
	create_mode="$1"
	r_name="$2"
	r_clone_url="$3"
	r_dest="$4"
	r_base="$5"
	branch_name="$6"
	r_base_branch="${7:-}"

	echo "=== [$r_name] Clone/worktree ==="

	# check if destination already exists
	if [ -d "$r_dest" ]; then
		echo "err: destination already exists: $r_dest"
		echo "CLONE_FAILED"
		exit 1
	fi

	if [ "$create_mode" = "clone" ]; then
		# clone mode: always clone fresh
		test -n "$r_clone_url" || r_clone_url="$(git -C "$r_base" remote get-url origin)"
		cs_create_clone_core "$r_clone_url" "$r_dest" "$branch_name" || {
			echo "CLONE_FAILED"
			exit 1
		}
		echo "$r_name" > "$r_dest/.git/CODESPACE_IS_CLONE"
	else
		# worktree mode: clone base repo first if needed
		if [ ! -d "$r_base/.git" ]; then
			echo "Base repo not found, cloning: $r_clone_url -> $r_base"
			git clone "$r_clone_url" "$r_base" || {
				echo "CLONE_FAILED"
				exit 1
			}
		fi
		# prune stale worktree references (e.g. from improperly removed worktrees)
		git -C "$r_base" worktree prune
		cs_create_worktree_core "$branch_name" "$r_base" "$r_dest" "$r_base_branch" || {
			echo "CLONE_FAILED"
			exit 1
		}
	fi

	echo "=== [$r_name] Post-create ==="
	cd "$r_dest" || {
		echo "POST_CREATE_FAILED"
		exit 1
	}
	cs_post_create "$r_dest" || {
		echo "POST_CREATE_FAILED"
		exit 1
	}

	echo "=== [$r_name] Done ==="
}

test -n "${CS_STACK_NO_RUN:-}" || {
	cs_stack_main "$@"
	exit $?
}