@dtt_siye/atool 1.1.0

package/lib/common.sh

@@ -0,0 +1,1041 @@
+#!/usr/bin/env bash
+# aTool - lib/common.sh
+# Shared functions: logging, JSON merge, path utilities, Superpowers download/cache
+
+set -euo pipefail
+
+ATOOL_VERSION="${ATOOL_VERSION:-$(cat "$(dirname "${BASH_SOURCE[0]}")/../VERSION" 2>/dev/null || echo "0.1.0")}"
+ATOOL_CACHE_DIR="${ATOOL_CACHE_DIR:-$HOME/.atool/cache}"
+ATOOL_BACKUP_DIR="${ATOOL_BACKUP_DIR:-$HOME/.atool/backups}"
+SUPERPOWERS_VERSION="${SUPERPOWERS_VERSION:-v5.0.6}"
+SUPERPOWERS_REPO="${SUPERPOWERS_REPO:-https://github.com/obra/superpowers.git}"
+
+# ── Colors ──────────────────────────────────────────────────────────────────
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+CYAN='\033[0;36m'
+BOLD='\033[1m'
+DIM='\033[2m'
+NC='\033[0m' # No Color
+
+# ── Platform Detection ───────────────────────────────────────────────────────
+ATOOL_PLATFORM="${ATOOL_PLATFORM:-$(uname -s 2>/dev/null || echo "Unknown")}"
+is_windows() { [[ "$ATOOL_PLATFORM" == *"MINGW"* || "$ATOOL_PLATFORM" == *"MSYS"* || "$ATOOL_PLATFORM" == *"CYGWIN"* ]]; }
+is_wsl() { [[ -f /proc/version ]] && grep -qi microsoft /proc/version 2>/dev/null; }
+
+# Cross-platform file checksum (md5 -q on macOS, md5sum on Linux, certutil on Windows)
+file_checksum() {
+    local file="$1"
+    if is_windows; then
+        certutil -hashfile "$file" MD5 2>/dev/null | grep -v ':' | tr -d ' \r\n' | tr 'A-F' 'a-f'
+    elif command -v md5 &>/dev/null && md5 -q "$file" &>/dev/null; then
+        md5 -q "$file"
+    else
+        md5sum "$file" 2>/dev/null | cut -d' ' -f1
+    fi
+}
+
+# Cross-platform stat mtime (macOS: stat -f %m, Linux: stat -c %Y, Windows: date)
+file_mtime() {
+    local file="$1"
+    if [[ "$(uname -s)" == "Darwin" ]]; then
+        stat -f "%m" "$file" 2>/dev/null
+    elif is_windows; then
+        # Use date -r (available in Git Bash / MSYS2) instead of PowerShell
+        date -r "$file" +%s 2>/dev/null || stat -c "%Y" "$file" 2>/dev/null
+    else
+        stat -c "%Y" "$file" 2>/dev/null
+    fi
+}
+
+# Cross-platform rsync replacement (uses cp -r on Windows)
+sync_dir() {
+    local src="$1" dest="$2"
+    if is_windows; then
+        # Match rsync semantics: trailing slash on src means "copy contents into dest"
+        if [[ "$src" == */ ]]; then
+            # src ends with / → copy contents of src into dest
+            mkdir -p "$dest"
+            rm -rf "${dest:?}/"*
+            cp -r "${src%/}"/* "${dest%/}/" 2>/dev/null || cp -r "${src%/}/"* "${dest%/}/" 2>/dev/null || true
+        else
+            # No trailing slash → copy src directory itself into dest's parent
+            rm -rf "$dest"
+            cp -r "$src" "$dest"
+        fi
+    else
+        rsync -a "$src" "$dest"
+    fi
+}
+
+# Cross-platform find with -quit equivalent
+find_first() {
+    local dir="$1" name_pattern="$2"
+    if [[ "$(uname -s)" == "Darwin" ]] || is_windows; then
+        find "$dir" -name "$name_pattern" 2>/dev/null | head -1
+    else
+        find "$dir" -name "$name_pattern" -print -quit 2>/dev/null
+    fi
+}
+
+# ── Logging ─────────────────────────────────────────────────────────────────
+
+log_info()  { echo -e "${GREEN}[INFO]${NC}  $*"; }
+log_warn()  { echo -e "${YELLOW}[WARN]${NC}  $*"; }
+log_error() { echo -e "${RED}[ERROR]${NC} $*" >&2; }
+log_step()  { echo -e "\n${BLUE}${BOLD}▶ $*${NC}"; }
+log_success() { echo -e "${GREEN}${BOLD}✓ $*${NC}"; }
+
+# ── Confirmation ────────────────────────────────────────────────────────────
+
+confirm() {
+    local message="$1"
+    local default="${2:-Y}"
+    local prompt
+
+    if [[ "$default" =~ ^[Yy]$ ]]; then
+        prompt="$message [Y/n] "
+    else
+        prompt="$message [y/N] "
+    fi
+
+    if [[ "${ATOOL_YES:-}" == "1" ]]; then
+        return 0
+    fi
+
+    while true; do
+        printf '%s' "${CYAN}? ${NC}${prompt}"
+        read -r answer
+        answer="${answer:-$default}"
+        case "$answer" in
+            [Yy]|[Yy][Ee][Ss]) return 0 ;;
+            [Nn]|[Nn][Oo]) return 1 ;;
+            *) echo "Please answer yes or no." ;;
+        esac
+    done
+}
+
+# ── Dry Run ─────────────────────────────────────────────────────────────────
+
+is_dry_run() { [[ "${ATOOL_DRY_RUN:-0}" == "1" ]]; }
+
+run_cmd() {
+    if is_dry_run; then
+        log_info "[DRY-RUN] $*"
+    else
+        "$@"
+    fi
+}
+
+# ── Path Utilities ──────────────────────────────────────────────────────────
+
+ensure_dir() {
+    local dir="$1"
+    # Always create directories - it's idempotent and safe
+    mkdir -p "$dir"
+}
+
+# ── IDE Config Directory Helpers (cross-platform) ─────────────────────────────
+
+get_claude_config_dir() {
+    if is_windows && [[ -n "${APPDATA:-}" ]]; then
+        cygpath -u "$APPDATA/claude" 2>/dev/null || echo "$HOME/.claude"
+    else
+        echo "$HOME/.claude"
+    fi
+}
+
+get_cursor_config_dir() {
+    if is_windows && [[ -n "${APPDATA:-}" ]]; then
+        cygpath -u "$APPDATA/Cursor" 2>/dev/null || echo "$HOME/.cursor"
+    else
+        echo "$HOME/.cursor"
+    fi
+}
+
+get_kiro_config_dir() {
+    if is_windows && [[ -n "${APPDATA:-}" ]]; then
+        cygpath -u "$APPDATA/Kiro" 2>/dev/null || echo "$HOME/.kiro"
+    else
+        echo "$HOME/.kiro"
+    fi
+}
+
+backup_file() {
+    local file="$1"
+    if [[ ! -f "$file" ]]; then return 0; fi
+
+    local timestamp
+    timestamp=$(date +%Y%m%d_%H%M%S)
+    local backup_name="${file}.atool-backup.${timestamp}"
+    ensure_dir "$ATOOL_BACKUP_DIR"
+
+    if is_dry_run; then
+        log_info "[DRY-RUN] backup: $file -> $backup_name"
+    else
+        cp "$file" "$backup_name"
+        log_info "Backed up: $file -> $backup_name"
+    fi
+}
+
+# ── JSON Utilities ──────────────────────────────────────────────────────────
+
+# Download a static jq binary from GitHub releases to ~/.atool/bin/
+# Works on macOS, Linux, and Windows (Git Bash/MSYS2/Cygwin)
+_download_jq() {
+    local atool_bin="$HOME/.atool/bin"
+    local jq_bin="$atool_bin/jq"
+    local jq_version="1.7.1"
+
+    # Already downloaded?
+    local jq_check="$jq_bin"
+    is_windows && jq_check="${jq_bin}.exe"
+    if [[ -x "$jq_check" ]] && "$jq_check" --version &>/dev/null; then
+        # Add to PATH if not already there
+        case ":${PATH}:" in
+            *":$atool_bin:"*) ;;
+            *) export PATH="$atool_bin:$PATH" ;;
+        esac
+        return 0
+    fi
+
+    log_info "jq not found — downloading static binary (v${jq_version})..."
+
+    # Determine platform and architecture
+    local platform arch suffix
+    suffix=""
+    if is_windows; then
+        platform="windows"
+        suffix=".exe"
+        # Detect architecture
+        local msystem="${MSYSTEM:-}"
+        if [[ "$msystem" == *"MINGW64"* || "$msystem" == *"UCRT64"* ]]; then
+            arch="amd64"
+        elif [[ "$msystem" == *"MINGW32"* ]]; then
+            arch="i386"
+        else
+            arch="amd64"  # Default to 64-bit
+        fi
+    elif [[ "$(uname -s)" == "Darwin" ]]; then
+        platform="macos"
+        if [[ "$(uname -m)" == "arm64" ]]; then
+            arch="arm64"
+        else
+            arch="amd64"
+        fi
+    else
+        platform="linux"
+        if [[ "$(uname -m)" == *"aarch64"* || "$(uname -m)" == *"arm64"* ]]; then
+            arch="arm64"
+        else
+            arch="amd64"
+        fi
+    fi
+
+    local url="https://github.com/jqlang/jq/releases/download/jq-${jq_version}/jq-${platform}-${arch}${suffix}"
+
+    ensure_dir "$atool_bin"
+
+    local tmp_download
+    tmp_download=$(mktemp)
+
+    if command -v curl &>/dev/null; then
+        if ! curl -fsSL "$url" -o "$tmp_download" 2>/dev/null; then
+            rm -f "$tmp_download"
+            log_warn "Failed to download jq from $url"
+            return 1
+        fi
+    elif command -v wget &>/dev/null; then
+        if ! wget -q "$url" -O "$tmp_download" 2>/dev/null; then
+            rm -f "$tmp_download"
+            log_warn "Failed to download jq from $url"
+            return 1
+        fi
+    else
+        log_warn "Neither curl nor wget available — cannot auto-download jq"
+        return 1
+    fi
+
+    mv "$tmp_download" "$jq_bin${suffix}"
+    chmod +x "$jq_bin${suffix}"
+
+    # Verify the download
+    if "$jq_bin${suffix}" --version &>/dev/null; then
+        log_success "jq downloaded to $jq_bin${suffix}"
+        # Add to PATH for current session
+        case ":${PATH}:" in
+            *":$atool_bin:"*) ;;
+            *) export PATH="$atool_bin:$PATH" ;;
+        esac
+        # Persist PATH for future sessions
+        _persist_jq_path "$atool_bin"
+        return 0
+    else
+        rm -f "$jq_bin${suffix}"
+        log_warn "Downloaded jq binary is not executable"
+        return 1
+    fi
+}
+
+# Persist ~/.atool/bin to shell rc file for future sessions
+# Args: ATOOL_BIN_DIR
+_persist_jq_path() {
+    local atool_bin="$1"
+    local rc_file=""
+
+    if is_windows; then
+        # On Windows (Git Bash), always use ~/.bashrc
+        rc_file="$HOME/.bashrc"
+    elif [[ -f "$HOME/.bashrc" ]]; then
+        rc_file="$HOME/.bashrc"
+    elif [[ -f "$HOME/.bash_profile" ]]; then
+        rc_file="$HOME/.bash_profile"
+    elif [[ -f "$HOME/.zshrc" ]]; then
+        rc_file="$HOME/.zshrc"
+    fi
+
+    [[ -z "$rc_file" ]] && return 0
+
+    # Already persisted?
+    if grep -q "$atool_bin" "$rc_file" 2>/dev/null; then
+        return 0
+    fi
+
+    printf '\n# Added by aTool - jq binary path\nexport PATH="%s:\$PATH"\n' "$atool_bin" >> "$rc_file"
+    log_info "Added $atool_bin to $(basename "$rc_file") for persistent access"
+}
+
+check_jq() {
+    if command -v jq &>/dev/null; then
+        return 0
+    fi
+
+    # Try auto-download first
+    if _download_jq; then
+        return 0
+    fi
+
+    # Fallback: show manual install instructions
+    local install_hint="brew install jq"
+    if is_windows; then
+        install_hint="choco install jq | scoop install jq | Download from https://jqlang.github.io/jq/"
+    fi
+    log_error "jq is required but not installed and auto-download failed."
+    log_error "Install manually: $install_hint"
+    log_error "Or re-run this script after installing jq."
+    exit 1
+}
+
+# Deep merge two JSON files. source is merged INTO target. Returns merged JSON to stdout.
+json_merge() {
+    local target_file="$1"
+    local source_file="$2"
+
+    check_jq
+
+    if [[ ! -f "$target_file" ]]; then
+        # Target doesn't exist, just return source
+        cat "$source_file"
+        return 0
+    fi
+
+    if [[ ! -f "$source_file" ]]; then
+        cat "$target_file"
+        return 0
+    fi
+
+    # Deep merge using jq --slurp
+    jq -s '.[0] * .[1]' "$target_file" "$source_file"
+}
+
+# Get a value from JSON file at a given path
+json_get() {
+    local file="$1"
+    local path="$2"
+    check_jq
+    jq -r "$path // empty" "$file" 2>/dev/null
+}
+
+# Set a value in a JSON file at a given path
+json_set() {
+    local file="$1"
+    local path="$2"
+    local value="$3"
+    check_jq
+    local tmp
+    tmp=$(mktemp)
+    jq "$path = $value" "$file" > "$tmp" && mv "$tmp" "$file"
+}
+
+# Check if a key exists in JSON
+json_has_key() {
+    local file="$1"
+    local path="$2"
+    check_jq
+    jq -e "$path" "$file" &>/dev/null
+}
+
+# ── Superpowers Download/Cache ─────────────────────────────────────────────
+
+get_superpowers_dir() {
+    echo "$ATOOL_CACHE_DIR/superpowers"
+}
+
+download_superpowers() {
+    local dest_dir="$1"
+    local cached_dir
+    cached_dir="$(get_superpowers_dir)"
+
+    # Check cache first
+    if [[ -d "$cached_dir" && -f "$cached_dir/.atool-superpowers-version" ]]; then
+        local cached_version
+        cached_version=$(cat "$cached_dir/.atool-superpowers-version")
+        if [[ "$cached_version" == "$SUPERPOWERS_VERSION" ]]; then
+            log_info "Using cached Superpowers ($SUPERPOWERS_VERSION)"
+            if [[ "$cached_dir" != "$dest_dir" ]]; then
+                ensure_dir "$dest_dir"
+                run_cmd sync_dir "$cached_dir/" "$dest_dir/"
+            fi
+            return 0
+        fi
+    fi
+
+    # Download from GitHub
+    log_info "Downloading Superpowers $SUPERPOWERS_VERSION..."
+    local tmpdir
+    tmpdir=$(mktemp -d)
+
+    if is_dry_run; then
+        log_info "[DRY-RUN] git clone --depth 1 --branch $SUPERPOWERS_VERSION $SUPERPOWERS_REPO $tmpdir/superpowers"
+        # Create a minimal structure for dry-run
+        ensure_dir "$dest_dir"
+        return 0
+    fi
+
+    if ! git clone --depth 1 --branch "$SUPERPOWERS_VERSION" \
+        "$SUPERPOWERS_REPO" "$tmpdir/superpowers" 2>/dev/null; then
+        log_warn "Failed to download Superpowers $SUPERPOWERS_VERSION"
+        log_warn "Skills installation will skip Superpowers"
+        rm -rf "$tmpdir"
+        return 1
+    fi
+
+    # Cache it
+    ensure_dir "$(dirname "$cached_dir")"
+    sync_dir "$tmpdir/superpowers/" "$cached_dir/"
+    echo "$SUPERPOWERS_VERSION" > "$cached_dir/.atool-superpowers-version"
+    log_success "Superpowers $SUPERPOWERS_VERSION downloaded and cached"
+
+    # Copy to destination if different
+    if [[ "$cached_dir" != "$dest_dir" ]]; then
+        ensure_dir "$dest_dir"
+        sync_dir "$cached_dir/" "$dest_dir/"
+    fi
+
+    rm -rf "$tmpdir"
+}
+
+# ── Skill Version Detection ─────────────────────────────────────────────────
+
+# Get Superpowers version from package.json in a directory
+# Args: SP_DIR (superpowers root directory)
+# Outputs: version string or "unknown"
+get_superpowers_version() {
+    local sp_dir="$1"
+    local pkg_json="$sp_dir/package.json"
+    if [[ -f "$pkg_json" ]]; then
+        jq -r '.version // "unknown"' "$pkg_json" 2>/dev/null
+    elif [[ -f "$sp_dir/.atool-superpowers-version" ]]; then
+        cat "$sp_dir/.atool-superpowers-version"
+    else
+        echo "unknown"
+    fi
+}
+
+# Get version of a single Superpowers skill via SKILL.md checksum
+# Args: SKILL_DIR (individual skill directory)
+# Outputs: checksum string or "none"
+get_superpowers_skill_version() {
+    local skill_dir="$1"
+    local skill_md="$skill_dir/SKILL.md"
+    if [[ -f "$skill_md" ]]; then
+        file_checksum "$skill_md"
+    else
+        echo "none"
+    fi
+}
+
+# Get the installed version of a skill from its target directory
+# Reads .atool-skill-version if present, falls back to checksum
+# Args: SKILL_DIR (installed skill directory)
+# Outputs: version string or "none"
+get_installed_skill_version() {
+    local skill_dir="$1"
+    local marker="$skill_dir/.atool-skill-version"
+    if [[ -f "$marker" ]]; then
+        cat "$marker"
+    elif [[ -f "$skill_dir/SKILL.md" ]]; then
+        file_checksum "$skill_dir/SKILL.md"
+    else
+        echo "none"
+    fi
+}
+
+# Get the source version of an aTool skill
+# Priority: VERSION file > frontmatter version: > SKILL.md checksum
+# Args: SKILL_DIR (source skill directory in aTool)
+# Outputs: version string or "none"
+get_atool_skill_version() {
+    local skill_dir="$1"
+
+    # 1. Check VERSION file
+    if [[ -f "$skill_dir/VERSION" ]]; then
+        cat "$skill_dir/VERSION"
+        return 0
+    fi
+
+    # 2. Check frontmatter version:
+    local skill_md="$skill_dir/SKILL.md"
+    if [[ -f "$skill_md" ]]; then
+        local fm_version
+        fm_version=$(sed -n '/^---$/,/^---$/p' "$skill_md" | grep -oE '^version:[[:space:]]*[0-9]+\.[0-9]+\.[0-9]+' | head -1 | sed 's/^version:[[:space:]]*//')
+        if [[ -n "$fm_version" ]]; then
+            echo "$fm_version"
+            return 0
+        fi
+
+        # 3. Fallback to checksum
+        file_checksum "$skill_md"
+        return 0
+    fi
+
+    echo "none"
+}
+
+# Determine whether a skill should be installed
+# Args: NAME, INSTALLED_VERSION, SOURCE_VERSION
+# Returns: 0 (install), 1 (skip)
+# Set ATOOL_FORCE=1 to always install
+should_install_skill() {
+    local name="$1" installed="$2" source="$3"
+
+    # Force mode: always install
+    if [[ "${ATOOL_FORCE:-0}" == "1" ]]; then
+        return 0
+    fi
+
+    # Not installed: install
+    if [[ "$installed" == "none" ]]; then
+        return 0
+    fi
+
+    # Same version: skip
+    if [[ "$installed" == "$source" ]]; then
+        return 1
+    fi
+
+    # Different version: install (update)
+    return 0
+}
+
+# Write a version marker file into an installed skill directory
+# Args: DIR, VERSION
+write_skill_version_marker() {
+    local dir="$1" version="$2"
+    run_cmd bash -c "echo '$version' > '$dir/.atool-skill-version'"
+}
+
+# ── IDE Detection ───────────────────────────────────────────────────────────
+
+detect_ides() {
+    local ides=()
+
+    # Claude Code CLI
+    if command -v claude &>/dev/null; then
+        ides+=("claude")
+    fi
+
+    # Cursor - check binary first, then config dir (cross-platform)
+    if command -v cursor &>/dev/null; then
+        ides+=("cursor")
+    else
+        local _cursor_dir
+        _cursor_dir=$(get_cursor_config_dir 2>/dev/null)
+        if [[ -d "$_cursor_dir" ]]; then
+            ides+=("cursor")
+        fi
+    fi
+
+    # Kiro - check binary first, then config dir (cross-platform)
+    if command -v kiro &>/dev/null; then
+        ides+=("kiro")
+    else
+        local _kiro_dir
+        _kiro_dir=$(get_kiro_config_dir 2>/dev/null)
+        if [[ -d "$_kiro_dir" ]]; then
+            ides+=("kiro")
+        fi
+    fi
+
+    echo "${ides[@]}"
+}
+
+# ── aTool marker ────────────────────────────────────────────────────────────
+
+mark_atool_config() {
+    local file="$1"
+    local marker='# Added by aTool'
+    if ! grep -qF "$marker" "$file" 2>/dev/null; then
+        echo "$marker" >> "$file"
+    fi
+}
+
+# ── Template Substitution ────────────────────────────────────────────────────
+
+# Replace {{KEY}} placeholders in a template file with provided values
+# Args: TEMPLATE_FILE OUTPUT_FILE [KEY=VALUE...]
+template_substitute() {
+    local template="$1" output="$2"; shift 2
+    local content
+    content=$(cat "$template")
+    for pair in "$@"; do
+        local key="${pair%%=*}" value="${pair##*=}"
+        content=$(echo "$content" | sed "s|{{${key}}}|${value}|g")
+    done
+    if ! is_dry_run; then
+        echo "$content" > "$output"
+    fi
+}
+
+# Replace {{#KEY}}...{{/KEY}} block placeholders with content from files
+# Expects metadata pairs where value starts with __BLOCK__:/path/to/file
+# Args: OUTPUT_FILE [KEY=__BLOCK__:/path...]
+template_substitute_blocks() {
+    local output="$1"; shift
+    [[ ! -f "$output" ]] && return 0
+
+    for pair in "$@"; do
+        local key="${pair%%=*}" value="${pair##*=}"
+
+        # Only process __BLOCK__ values
+        if [[ "$value" != __BLOCK__:* ]]; then
+            continue
+        fi
+
+        local block_file="${value#__BLOCK__:}"
+        if [[ ! -f "$block_file" ]]; then
+            continue
+        fi
+
+        local tmp_result
+        tmp_result=$(mktemp)
+
+        # Use awk with -v repfile to pass the block file path
+        # awk reads the replacement file in BEGIN block
+        awk -v key="$key" -v repfile="$block_file" '
+            BEGIN {
+                in_block = 0
+                rep = ""
+                while ((getline line < repfile) > 0) {
+                    rep = rep line "\n"
+                }
+                close(repfile)
+            }
+            !in_block && index($0, "{{#" key "}}") > 0 {
+                in_block = 1
+                before = substr($0, 1, index($0, "{{#" key "}}") - 1)
+                rest = substr($0, index($0, "{{#" key "}}") + length("{{#" key "}}"))
+                if (index(rest, "{{/" key "}}") > 0) {
+                    after = substr(rest, index(rest, "{{/" key "}}") + length("{{/" key "}}"))
+                    printf "%s%s%s\n", before, rep, after
+                    in_block = 0
+                } else {
+                    printf "%s%s", before, rep
+                }
+                next
+            }
+            in_block && index($0, "{{/" key "}}") > 0 {
+                after = substr($0, index($0, "{{/" key "}}") + length("{{/" key "}}"))
+                printf "%s\n", after
+                in_block = 0
+                next
+            }
+            !in_block { print }
+        ' "$output" > "$tmp_result"
+
+        if ! is_dry_run; then
+            cp "$tmp_result" "$output"
+        fi
+
+        rm -f "$tmp_result"
+    done
+}
+
+# Remove remaining unresolved block markers ({{#KEY}} and {{/KEY}}) from a file,
+# keeping the content between them intact.
+# This is called after template_substitute_blocks to clean up any block markers
+# that had no replacement data provided (e.g., NEWCOMER_CHECKLIST, RELATED_DOCS).
+# Args: OUTPUT_FILE
+strip_block_markers() {
+    local output="$1"
+    [[ ! -f "$output" ]] && return 0
+
+    # Only process if there are block markers
+    grep -q '{{#' "$output" 2>/dev/null || return 0
+
+    local tmp_result
+    tmp_result=$(mktemp)
+
+    # Remove {{#KEY}} and {{/KEY}} lines, keeping everything else
+    awk '!/^{{#[A-Z_]+}}$/ && !/^{{\/[A-Z_]+}}$/' "$output" > "$tmp_result"
+
+    if ! is_dry_run; then
+        cp "$tmp_result" "$output"
+    fi
+
+    rm -f "$tmp_result"
+}
+
+# ── Project Metadata Extraction ─────────────────────────────────────────────
+
+# Extract project metadata from signal files as KEY=VALUE pairs
+# Args: PROJECT_DIR
+# Outputs: key=value lines (PROJECT_NAME, PROJECT_VERSION, PROJECT_DESCRIPTION, STACK_TYPE, STACK_DESCRIPTION)
+extract_project_metadata() {
+    local dir="$1"
+
+    # shellcheck source=lib/detect-stack.sh
+    source "${ATOOL_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}/lib/detect-stack.sh"
+
+    local stack description
+    stack=$(detect_stack "$dir")
+    description=$(get_stack_description "$stack")
+
+    echo "STACK_TYPE=${stack}"
+    echo "STACK_DESCRIPTION=${description}"
+
+    # Tauri (src-tauri/tauri.conf.json takes priority over plain Cargo.toml)
+    if [[ -f "$dir/src-tauri/tauri.conf.json" ]]; then
+        echo "PROJECT_NAME=$(jq -r '.productName // empty' "$dir/src-tauri/tauri.conf.json" 2>/dev/null || echo "unknown")"
+        echo "PROJECT_VERSION=$(jq -r '.version // empty' "$dir/src-tauri/tauri.conf.json" 2>/dev/null || echo "unknown")"
+        echo "PROJECT_DESCRIPTION=Tauri Desktop App"
+        return 0
+    fi
+
+    # package.json (Node.js / Web / React Native)
+    if [[ -f "$dir/package.json" ]]; then
+        echo "PROJECT_NAME=$(jq -r '.name // empty' "$dir/package.json" 2>/dev/null || echo "unknown")"
+        echo "PROJECT_VERSION=$(jq -r '.version // empty' "$dir/package.json" 2>/dev/null || echo "unknown")"
+        echo "PROJECT_DESCRIPTION=$(jq -r '.description // empty' "$dir/package.json" 2>/dev/null || echo "")"
+        return 0
+    fi
+
+    # pom.xml (Java / Maven)
+    if [[ -f "$dir/pom.xml" ]]; then
+        echo "PROJECT_NAME=$(grep -m1 '<artifactId>' "$dir/pom.xml" 2>/dev/null | sed 's|.*<artifactId>||;s|</artifactId>.*||' || echo "unknown")"
+        echo "PROJECT_VERSION=$(grep -m1 '<version>' "$dir/pom.xml" 2>/dev/null | sed 's|.*<version>||;s|</version>.*||' || echo "unknown")"
+        echo "PROJECT_DESCRIPTION=$(grep -m1 '<description>' "$dir/pom.xml" 2>/dev/null | sed 's|.*<description>||;s|</description>.*||' || echo "")"
+        # Derive package path from groupId (com.example → com/example)
+        local _group_id
+        _group_id=$(grep -m1 '<groupId>' "$dir/pom.xml" 2>/dev/null | sed 's|.*<groupId>||;s|</groupId>.*||' || echo "")
+        [[ -n "$_group_id" ]] && echo "PACKAGE_PATH=${_group_id//.//}"
+        return 0
+    fi
+
+    # build.gradle / build.gradle.kts (Java / Android)
+    if [[ -f "$dir/build.gradle" || -f "$dir/build.gradle.kts" ]]; then
+        local gradle_file="$dir/build.gradle"
+        [[ -f "$dir/build.gradle.kts" ]] && gradle_file="$dir/build.gradle.kts"
+        echo "PROJECT_NAME=$(grep -m1 'applicationId\|archivesBaseName' "$gradle_file" 2>/dev/null | sed 's|.*"\(.*\)".*|\1|' || echo "unknown")"
+        echo "PROJECT_VERSION=$(grep -m1 'versionName\|version' "$gradle_file" 2>/dev/null | grep -oE '"[^"]*"' | head -1 | tr -d '"' || echo "unknown")"
+        echo "PROJECT_DESCRIPTION="
+        # Derive package path from group or applicationId
+        local _gradle_group
+        _gradle_group=$(grep -m1 'group\s*=' "$gradle_file" 2>/dev/null | sed 's|.*"\(.*\)".*|\1|' || echo "")
+        [[ -z "$_gradle_group" ]] && _gradle_group=$(grep -m1 'applicationId' "$gradle_file" 2>/dev/null | sed 's|.*"\(.*\)".*|\1|' || echo "")
+        [[ -n "$_gradle_group" ]] && echo "PACKAGE_PATH=${_gradle_group//.//}"
+        return 0
+    fi
+
+    # Cargo.toml (Rust)
+    if [[ -f "$dir/Cargo.toml" ]]; then
+        echo "PROJECT_NAME=$(grep -m1 '^name' "$dir/Cargo.toml" 2>/dev/null | sed 's|name = "||;s|"$||' || echo "unknown")"
+        echo "PROJECT_VERSION=$(grep -m1 '^version' "$dir/Cargo.toml" 2>/dev/null | sed 's|version = "||;s|"$||' || echo "unknown")"
+        echo "PROJECT_DESCRIPTION=$(grep -m1 '^description' "$dir/Cargo.toml" 2>/dev/null | sed 's|description = "||;s|"$||' || echo "")"
+        return 0
+    fi
+
+    # go.mod (Go)
+    if [[ -f "$dir/go.mod" ]]; then
+        echo "PROJECT_NAME=$(head -1 "$dir/go.mod" 2>/dev/null | awk '{print $2}' || echo "unknown")"
+        echo "PROJECT_VERSION="
+        echo "PROJECT_DESCRIPTION="
+        return 0
+    fi
+
+    # pyproject.toml (Python)
+    if [[ -f "$dir/pyproject.toml" ]]; then
+        echo "PROJECT_NAME=$(grep -m1 'name' "$dir/pyproject.toml" 2>/dev/null | head -1 | sed 's|.*name = "||;s|"$||;s|.*name = '"'"'||;s|'"'"'$||' || echo "unknown")"
+        echo "PROJECT_VERSION=$(grep -m1 'version' "$dir/pyproject.toml" 2>/dev/null | head -1 | sed 's|.*version = "||;s|"$||;s|.*version = '"'"'||;s|'"'"'$||' || echo "unknown")"
+        echo "PROJECT_DESCRIPTION=$(grep -m1 'description' "$dir/pyproject.toml" 2>/dev/null | head -1 | sed 's|.*description = "||;s|"$||' || echo "")"
+        return 0
+    fi
+
+    # requirements.txt (Python)
+    if [[ -f "$dir/requirements.txt" ]]; then
+        echo "PROJECT_NAME=$(basename "$(cd "$dir" && pwd)")"
+        echo "PROJECT_VERSION="
+        echo "PROJECT_DESCRIPTION="
+        return 0
+    fi
+
+    # pubspec.yaml (Flutter)
+    if [[ -f "$dir/pubspec.yaml" ]]; then
+        echo "PROJECT_NAME=$(grep -m1 '^name:' "$dir/pubspec.yaml" 2>/dev/null | awk '{print $2}' || echo "unknown")"
+        echo "PROJECT_VERSION=$(grep -m1 '^version:' "$dir/pubspec.yaml" 2>/dev/null | awk '{print $2}' || echo "unknown")"
+        echo "PROJECT_DESCRIPTION=$(grep -m1 '^description:' "$dir/pubspec.yaml" 2>/dev/null | sed 's|^description: *||' || echo "")"
+        return 0
+    fi
+
+    # oh-package.json5 (HarmonyOS)
+    if [[ -f "$dir/oh-package.json5" ]]; then
+        echo "PROJECT_NAME=$(jq -r '.name // empty' "$dir/oh-package.json5" 2>/dev/null || echo "unknown")"
+        echo "PROJECT_VERSION=$(jq -r '.version // empty' "$dir/oh-package.json5" 2>/dev/null || echo "unknown")"
+        echo "PROJECT_DESCRIPTION=$(jq -r '.description // empty' "$dir/oh-package.json5" 2>/dev/null || echo "")"
+        return 0
+    fi
+
+    # Package.swift (Swift/iOS)
+    if [[ -f "$dir/Package.swift" ]]; then
+        echo "PROJECT_NAME=$(grep -m1 'name:' "$dir/Package.swift" 2>/dev/null | sed 's|.*name: "||;s|".*||' || echo "unknown")"
+        echo "PROJECT_VERSION="
+        echo "PROJECT_DESCRIPTION="
+        return 0
+    fi
+
+    # Fallback: directory name
+    echo "PROJECT_NAME=$(basename "$(cd "$dir" && pwd)")"
+    echo "PROJECT_VERSION="
+    echo "PROJECT_DESCRIPTION="
+}
+
+# ── Skill Catalog Scanner ──────────────────────────────────────────────────
+
+# Scan installed skills directory and output a structured catalog
+# Reads only the first 10 lines of each SKILL.md for performance
+# Args: SKILLS_DIR (e.g. ~/.claude/skills)
+# Outputs: structured text grouped by category
+scan_skills_catalog() {
+    local skills_dir="$1"
+    if [[ ! -d "$skills_dir" ]]; then
+        return 0
+    fi
+
+    local conventions="" superpowers_list="" office=""
+    local arch_design="" quality_review="" documentation="" planning=""
+
+    for skill_dir in "$skills_dir"/*/; do
+        [[ ! -d "$skill_dir" ]] && continue
+        local skill_name
+        skill_name=$(basename "$skill_dir")
+        [[ -L "$skill_dir" ]] && continue
+        [[ "$skill_name" == "_superpowers" ]] && continue
+
+        local skill_md="$skill_dir/SKILL.md"
+        [[ ! -f "$skill_md" ]] && continue
+
+        # Extract description from frontmatter (first 10 lines only)
+        local desc=""
+        desc=$(head -10 "$skill_md" | sed -n '/^---$/,/^---$/p' | grep '^description:' | head -1 | sed 's/^description:[[:space:]]*//')
+        if [[ -z "$desc" ]]; then
+            desc=$(head -10 "$skill_md" | grep -i '^#' | head -1 | sed 's/^#*\s*//' || echo "$skill_name")
+        fi
+
+        # Categorize
+        case "$skill_name" in
+            *-conventions)
+                conventions="${conventions}- ${skill_name}: ${desc}
+"
+                ;;
+            pdf|docx|pptx|xlsx)
+                office="${office}- ${skill_name}: ${desc}
+"
+                ;;
+            # Architecture & Design
+            software-architecture|ai-project-architecture|ui-ux-pro)
+                arch_design="${arch_design}- ${skill_name}: ${desc}
+"
+                ;;
+            # Quality & Review
+            code-review|project-analyze|project-query|verification-before-completion)
+                quality_review="${quality_review}- ${skill_name}: ${desc}
+"
+                ;;
+            # Documentation
+            doc-coauthoring|doc-standards-enforcer|requirements-writer)
+                documentation="${documentation}- ${skill_name}: ${desc}
+"
+                ;;
+            # Planning & Dispatch
+            writing-plans|smart-dispatch|brainstorming|clarify-before-build)
+                planning="${planning}- ${skill_name}: ${desc}
+"
+                ;;
+            *)
+                planning="${planning}- ${skill_name}: ${desc}
+"
+                ;;
+        esac
+    done
+
+    # Check for Superpowers skills
+    local sp_dir="$skills_dir"
+    if [[ -d "$skills_dir/_superpowers/skills" ]]; then
+        sp_dir="$skills_dir/_superpowers/skills"
+    fi
+    for skill_dir in "$sp_dir"/*/; do
+        [[ ! -d "$skill_dir" ]] && continue
+        local skill_name
+        skill_name=$(basename "$skill_dir")
+        [[ -L "$skill_dir" ]] && continue
+        local sp_md="$skill_dir/SKILL.md"
+        [[ ! -f "$sp_md" ]] && continue
+        local desc=""
+        desc=$(head -10 "$sp_md" | sed -n '/^---$/,/^---$/p' | grep '^description:' | head -1 | sed 's/^description:[[:space:]]*//')
+        if [[ -z "$desc" ]]; then
+            desc=$(head -10 "$sp_md" | grep -i '^#' | head -1 | sed 's/^#*\s*//' || echo "$skill_name")
+        fi
+        superpowers_list="${superpowers_list}- ${skill_name}: ${desc}
+"
+    done
+
+    # Output catalog
+    if [[ -n "$conventions" ]]; then
+        echo "## Conventions Skills (auto-apply when relevant)"
+        printf '%s' "$conventions"
+        echo ""
+    fi
+    if [[ -n "$arch_design" ]]; then
+        echo "## Architecture & Design"
+        printf '%s' "$arch_design"
+        echo ""
+    fi
+    if [[ -n "$quality_review" ]]; then
+        echo "## Quality & Review"
+        printf '%s' "$quality_review"
+        echo ""
+    fi
+    if [[ -n "$documentation" ]]; then
+        echo "## Documentation"
+        printf '%s' "$documentation"
+        echo ""
+    fi
+    if [[ -n "$planning" ]]; then
+        echo "## Planning & Other"
+        printf '%s' "$planning"
+        echo ""
+    fi
+    if [[ -n "$superpowers_list" ]]; then
+        echo "## Superpowers Skills"
+        printf '%s' "$superpowers_list"
+        echo ""
+    fi
+    if [[ -n "$office" ]]; then
+        echo "## Office Skills"
+        printf '%s' "$office"
+        echo ""
+    fi
+}
+
+# Map a detected stack to its primary conventions skill name
+# Args: STACK_TYPE (e.g. "java-spring")
+# Outputs: conventions skill name or empty string
+stack_to_conventions_skill() {
+    local stack="$1"
+    case "$stack" in
+        java-spring|java)       echo "java-conventions" ;;
+        android-kotlin)         echo "android-conventions" ;;
+        harmony)                echo "harmony-conventions" ;;
+        web-nextjs|web-react|web-vue|web-svelte) echo "web-conventions" ;;
+        mobile-react-native)    echo "react-native-conventions" ;;
+        mobile-flutter)         echo "flutter-conventions" ;;
+        mobile-swift)           echo "swift-conventions" ;;
+        python)                 echo "python-conventions" ;;
+        rust|rust-tauri)        echo "rust-conventions" ;;
+        go)                     echo "go-conventions" ;;
+        devops|devops-k8s)      echo "devops-conventions" ;;
+        *)                      echo "" ;;
+    esac
+}
+
+# Count source files modified after reference doc file(s)
+# Args: PROJECT_DIR, REF_FILE [REF_FILE2 ...] (relative paths, e.g. "README.md" "UI_STYLE.md")
+# Outputs: count of source files newer than the OLDEST reference file
+# If no reference file exists, outputs 0
+count_stale_docs() {
+    local project_dir="$1"
+    shift
+
+    # Find the oldest mtime among all provided reference files
+    local oldest_mtime=""
+    local found_any=false
+    for ref_file in "$@"; do
+        local ref_path="$project_dir/$ref_file"
+        if [[ -f "$ref_path" ]]; then
+            local ref_mtime
+            ref_mtime=$(file_mtime "$ref_path")
+            if ! $found_any || [[ "$ref_mtime" -lt "$oldest_mtime" ]]; then
+                oldest_mtime="$ref_mtime"
+            fi
+            found_any=true
+        fi
+    done
+
+    if ! $found_any; then
+        echo "0"
+        return 0
+    fi
+
+    local count=0
+
+    # Check common source directories for files newer than the oldest reference
+    while IFS= read -r src_file; do
+        [[ -z "$src_file" ]] && continue
+        local src_mtime
+        src_mtime=$(file_mtime "$src_file")
+        if [[ "$src_mtime" -gt "$oldest_mtime" ]]; then
+            count=$((count + 1))
+        fi
+    done < <(find "$project_dir" -type f \
+        \( -name '*.java' -o -name '*.py' -o -name '*.ts' -o -name '*.tsx' \
+        -o -name '*.js' -o -name '*.jsx' -o -name '*.vue' -o -name '*.svelte' \
+        -o -name '*.go' -o -name '*.rs' -o -name '*.kt' -o -name '*.swift' \
+        -o -name '*.dart' -o -name '*.ets' -o -name '*.sh' -o -name '*.html' \
+        \) -not -path '*/node_modules/*' -not -path '*/.git/*' \
+        -not -path '*/.atool-docs/*' -not -path '*/build/*' \
+        -not -path '*/dist/*' -not -path '*/target/*' \
+        2>/dev/null | head -200)
+
+    echo "$count"
+}
+
+# ── Version info ────────────────────────────────────────────────────────────
+
+show_version() {
+    echo "aTool v${ATOOL_VERSION}"
+}
+
+show_banner() {
+    echo -e "${CYAN}${BOLD}"
+    cat <<'EOF'
+    ╔══════════════════════════════════════╗
+    ║          aTool - AI Dev Toolkit       ║
+    ║   One-command AI IDE configuration    ║
+    ╚══════════════════════════════════════╝
+EOF
+    echo -e "${NC}"
+    echo -e "  Version: ${ATOOL_VERSION}"
+    echo ""
+}