@dtt_siye/atool 1.1.0

package/lib/install-kiro.sh

@@ -0,0 +1,543 @@
+#!/usr/bin/env bash
+# aTool - lib/install-kiro.sh
+# Kiro IDE installation (skills -> consolidated steering Markdown with YAML front matter)
+
+set -euo pipefail
+
+# These functions are sourced by the parent script, not run directly.
+# common.sh must already be loaded.
+
+# ── Category Mapping ──────────────────────────────────────────────────────
+
+# Convert a single SKILL.md to Kiro steering Markdown format (legacy / project-level helper)
+# Args: SKILL_DIR, OUTPUT_FILE
+skill_to_steering_yaml() {
+    local skill_dir="$1"
+    local output_file="$2"
+    local skill_name
+    skill_name=$(basename "$skill_dir")
+
+    local skill_md="$skill_dir/SKILL.md"
+    if [[ ! -f "$skill_md" ]]; then
+        return 1
+    fi
+
+    # Extract description from first heading
+    local description
+    description=$(head -5 "$skill_md" | grep -i '^#' | head -1 | sed 's/^#*\s*//' || echo "$skill_name skill")
+
+    # Write Markdown front matter
+    cat > "$output_file" <<MDFRONT
+---
+inclusion: auto
+name: atool-${skill_name}
+description: "${description}"
+---
+
+MDFRONT
+
+    # Append skill content directly (no indentation)
+    cat "$skill_md" >> "$output_file"
+}
+
+# ── Skill Categorization ────────────────────────────────────────────────────
+
+# Map a skill name to its consolidated steering category
+# Args: SKILL_NAME
+# Outputs: category name (e.g., "core-workflow", "analysis"), empty to skip
+get_kiro_steering_category() {
+    local skill_name="$1"
+    case "$skill_name" in
+        # Core workflow skills — always in context
+        atool-init|brainstorming|clarify-before-build|writing-plans|executing-plans|smart-dispatch|finishing-a-development-branch)
+            echo "core-workflow" ;;
+        # project-analyze is too large (~88KB) to consolidate — separate file
+        project-analyze)
+            echo "project-analyze" ;;
+        # project-query depends on project-analyze output — merged into project-analyze steering
+        project-query)
+            echo "project-analyze" ;;
+        # Code review is detail-heavy (8 dimensions) — separate file, manual activation
+        code-review)
+            echo "code-review" ;;
+        # Analysis skills — merged into core-workflow for efficiency
+        find-skills)
+            echo "core-workflow" ;;
+        # Verification handled by superpowers version — skip duplicate
+        verification-before-completion)
+            echo "" ;;
+        # Conventions handled by project-level template (kiro-steering.{stack}.md)
+        *-conventions)
+            echo "" ;;
+        # Office
+        pdf|docx|pptx|xlsx)
+            echo "office" ;;
+        # Architecture / design / docs
+        software-architecture|ai-project-architecture|ui-ux-pro|requirements-writer|doc-coauthoring|doc-standards-enforcer)
+            echo "design" ;;
+        # Testing
+        webapp-testing)
+            echo "testing" ;;
+        # Catch-all
+        *)
+            echo "misc" ;;
+    esac
+}
+
+# Map superpowers skill names to categories
+# Args: SKILL_NAME
+# Outputs: category name
+get_superpowers_kiro_category() {
+    local skill_name="$1"
+    case "$skill_name" in
+        # Essential — always needed
+        using-superpowers|brainstorming|verification-before-completion)
+            echo "core-workflow" ;;
+        # Quality — only during implementation/debugging
+        test-driven-development|systematic-debugging)
+            echo "quality" ;;
+        # Advanced — manual activation
+        dispatching-parallel-agents|subagent-driven-development|using-git-worktrees|requesting-code-review|receiving-code-review|writing-skills|executing-plans|writing-plans|finishing-a-development-branch)
+            echo "superpowers-advanced" ;;
+        # Default to core-workflow for unknown superpowers skills
+        *)
+            echo "core-workflow" ;;
+    esac
+}
+
+# ── Content Extraction ─────────────────────────────────────────────────────
+
+# Extract condensed instructions from a SKILL.md
+# Trims long code blocks (>8 lines) while preserving structure
+# Args: SKILL_MD_PATH
+# Outputs: condensed content to stdout
+extract_condensed_skill() {
+    local skill_md="$1"
+    awk '
+    BEGIN { fm = 0 }
+    /^---$/ { fm++; next }
+    fm < 2 { next }
+    /^```/ {
+        in_code++
+        if (in_code % 2 == 1) { code_lines = 0; print; next }
+    }
+    in_code % 2 == 1 {
+        code_lines++
+        if (code_lines <= 8) print
+        else if (code_lines == 9) print "    # ... (condensed)"
+        next
+    }
+    { print }
+    ' "$skill_md"
+}
+
+# Extract ultra-condensed instructions for always-in-context steering
+# Strips all code blocks, keeps headers + first 3 lines per section
+# Args: SKILL_MD_PATH
+# Outputs: ultra-condensed content to stdout
+extract_ultra_condensed_skill() {
+    local skill_md="$1"
+    awk '
+    BEGIN { section_lines = 0; fm = 0 }
+    /^---$/ { fm++; next }
+    fm < 2 { next }
+    /^```/ { in_code++; next }
+    in_code % 2 == 1 { next }
+    /^#+ / { print ""; print; section_lines = 0; next }
+    section_lines < 3 && NF > 0 { print; section_lines++; next }
+    NF == 0 { next }
+    ' "$skill_md"
+}
+
+# ── Inclusion Mode Helper ──────────────────────────────────────────────────
+
+# Get the Kiro inclusion mode for a steering category
+# Args: CATEGORY
+# Outputs: inclusion mode (always, auto, fileMatch, manual)
+_kiro_inclusion_for_category() {
+    local category="$1"
+    case "$category" in
+        # Always in context — essential for every conversation
+        core-workflow)
+            echo "always" ;;
+        # Quality skills — auto-load for test/debug files
+        quality)
+            echo "fileMatch" ;;
+        # Loaded on demand — too large or specialized for always
+        project-analyze|superpowers-advanced|misc|code-review|design|office|analysis)
+            echo "manual" ;;
+        # File type matching
+        testing)
+            echo "fileMatch" ;;
+        # Default
+        *)
+            echo "manual" ;;
+    esac
+}
+
+# ── Consolidated Steering Generator ───────────────────────────────────────
+
+# Generate consolidated Kiro steering files from skills
+# Groups skills by category, generates one Markdown file per category
+# Args: STAGING_DIR, SKILLS_DIRS..., CATEGORY_FUNC
+generate_consolidated_steering() {
+    local staging_dir="$1"
+    local category_func="$2"
+    shift 2
+    local skills_dirs=("$@")
+
+    ensure_dir "$staging_dir"
+
+    local tmpdir
+    tmpdir=$(mktemp -d)
+
+    # Collect category names
+    # Pre-define known categories in desired order
+    local categories=(core-workflow quality project-analyze office design testing misc superpowers-advanced)
+
+    # Initialize category content files
+    for cat in "${categories[@]}"; do
+        : > "$tmpdir/${cat}.txt"
+    done
+
+    # Group skills into categories
+    for skills_base in "${skills_dirs[@]}"; do
+        [[ ! -d "$skills_base" ]] && continue
+        for skill_dir in "$skills_base"/*/; do
+            [[ ! -d "$skill_dir" ]] && continue
+            local skill_name
+            skill_name=$(basename "$skill_dir")
+            [[ "$skill_name" == "_superpowers" ]] && continue
+            [[ -L "$skill_dir" ]] && continue
+
+            local skill_md="$skill_dir/SKILL.md"
+            [[ ! -f "$skill_md" ]] && continue
+
+            local category
+            category=$("$category_func" "$skill_name")
+
+            # Skip skills with no category (e.g., conventions handled by template)
+            [[ -z "$category" ]] && continue
+
+            # Determine condensation level based on inclusion mode
+            local inclusion
+            inclusion=$(_kiro_inclusion_for_category "$category")
+            local extract_func="extract_condensed_skill"
+            if [[ "$inclusion" == "always" ]]; then
+                extract_func="extract_ultra_condensed_skill"
+            fi
+
+            # Append content to category file using appropriate condensation
+            {
+                echo ""
+                echo "## Skill: $skill_name"
+                echo ""
+                $extract_func "$skill_md"
+            } >> "$tmpdir/${category}.txt"
+        done
+    done
+
+    # Generate one Markdown steering file per non-empty category
+    for cat in "${categories[@]}"; do
+        local cat_file="$tmpdir/${cat}.txt"
+        [[ ! -s "$cat_file" ]] && continue
+
+        local md_file="$staging_dir/atool-${cat}.md"
+
+        # Get inclusion mode for this category
+        local inclusion
+        inclusion=$(_kiro_inclusion_for_category "$cat")
+
+        # Determine extra front matter fields
+        local extra_front_matter=""
+        case "$cat" in
+            testing)
+                extra_front_matter=$'\n'"fileMatchPattern:"$'\n'"  - \"*.test.*\""$'\n'"  - \"*.spec.*\""
+                ;;
+        esac
+
+        # Write Markdown front matter
+        cat > "$md_file" <<MDFRONT
+---
+inclusion: ${inclusion}${extra_front_matter}
+name: atool-${cat}
+description: "aTool ${cat} skills (consolidated)"
+---
+
+MDFRONT
+
+        # For manual inclusion files, add a brief index of contained skills
+        if [[ "$inclusion" == "manual" ]]; then
+            echo "Enable this steering file in Kiro's steering panel to access these skills." >> "$md_file"
+            echo "" >> "$md_file"
+        fi
+
+        # Append content directly (no indentation)
+        cat "$cat_file" >> "$md_file"
+
+        log_info "Generated consolidated steering: atool-${cat}.md (${inclusion})"
+    done
+
+    # Cleanup temp directory
+    rm -rf "$tmpdir"
+}
+
+# ── Hook-Equivalent Steering ──────────────────────────────────────────────
+
+# Generate session-context steering (replaces session-start hook)
+# Args: STAGING_DIR, ATOOL_ROOT
+generate_kiro_session_context() {
+    local staging_dir="$1"
+    local atool_root="$2"
+    local md_file="$staging_dir/atool-session-context.md"
+
+    local version="${ATOOL_VERSION:-unknown}"
+
+    # Scan installed skills (static snapshot)
+    local skills_catalog
+    skills_catalog=$(scan_skills_catalog "$HOME/.claude/skills" 2>/dev/null || echo "Skills not yet installed - run ./install.sh first")
+
+    # Write Markdown front matter
+    cat > "$md_file" <<MDFRONT
+---
+inclusion: always
+name: atool-session-context
+description: "aTool session context: version, skill catalog, clarify rules, doc sync"
+---
+
+MDFRONT
+
+    # Append version info
+    echo "You have aTool v${version} active." >> "$md_file"
+    echo "" >> "$md_file"
+
+    # Append skill catalog (no indentation)
+    cat >> "$md_file" <<< "$skills_catalog"
+
+    # Append doc-sync rules (clarify rules are in core-workflow's clarify-before-build skill — no duplicate)
+    cat >> "$md_file" <<'RULES'
+
+## Document Sync (HARD RULE)
+
+Every time you modify a source file (.ts/.tsx/.js/.jsx/.vue/.svelte/.rs/.py/.go/.java/.kt/.swift/.dart/.ets/.sh):
+1. Check if README.md, COMPONENT.md, UI_STYLE.md, or docs/ need updating
+2. If docs are stale (source files newer than docs), update them BEFORE claiming task is done
+3. If docs are stale, the task is NOT complete — this is a gate, not a suggestion
+
+## On-Demand Skills
+
+Additional skills available as steering files — enable in Kiro's steering panel (.kiro/steering/):
+atool-code-review, atool-project-analyze, atool-design, atool-office, atool-superpowers-advanced, atool-misc
+RULES
+
+    log_info "Generated hook-equivalent: atool-session-context.md"
+}
+
+# Generate sub-agent fallback instructions for Kiro
+# Args: STAGING_DIR
+generate_kiro_agent_fallback() {
+    local staging_dir="$1"
+    local md_file="$staging_dir/atool-agent-fallback.md"
+
+    cat > "$md_file" <<'MDCONTENT'
+---
+inclusion: always
+name: atool-agent-fallback
+description: "Sequential analysis mode and agent coordination fallback for Kiro"
+---
+
+## Sequential Analysis Mode
+
+Kiro does not support parallel sub-agents. When performing deep analysis:
+
+1. Analyze modules sequentially (one at a time)
+2. After completing each module, briefly summarize findings before moving to next
+3. For large projects (>200 files), suggest breaking analysis into multiple sessions
+
+## When to Use Sequential Mode
+
+- When user asks to "analyze project" / "分析项目" / "deep analysis"
+- When running project-analyze at L2/L3 depth
+- When code review covers multiple modules
+
+## Code Review Adaptation
+
+When `/code-review` is invoked in Kiro:
+1. Do NOT dispatch parallel sub-agents — analyze files sequentially in the main agent
+2. Execute only Critical-level checks (hardcoded credentials, SQL injection, empty catch, unreachable code, complexity >15, function length >120, layer violations, deprecated critical APIs)
+3. Output findings as inline Markdown feedback — do NOT generate CODE_REVIEW.md or summary.json
+4. If `.atool-docs/knowledge-graph.json` exists, use it for coupling analysis; otherwise skip dimension 7
+
+## Progress Reporting
+
+After each module analysis, report:
+- Module name and purpose
+- Key findings
+- Issues discovered
+- Next module to analyze
+
+## Workflow Skills Adaptation
+
+Skills that normally use parallel agents (smart-dispatch, subagent-driven-development) should:
+- Execute tasks sequentially in a single agent
+- Report progress after each task
+- Ask user if they want to continue with remaining tasks
+MDCONTENT
+
+    log_info "Generated hook-equivalent: atool-agent-fallback.md"
+}
+
+# ── Legacy File Cleanup ────────────────────────────────────────────────────
+
+# Remove old per-skill steering files from staging
+# Args: STAGING_DIR
+cleanup_legacy_kiro_steering() {
+    local steering_dir="$1"
+    local legacy_count=0
+
+    # Clean up old .yaml steering files (pre-format-fix)
+    for f in "$steering_dir"/atool-*.yaml "$steering_dir"/superpowers-*.yaml; do
+        [[ ! -f "$f" ]] && continue
+        rm -f "$f"
+        legacy_count=$((legacy_count + 1))
+    done
+
+    # Clean up legacy per-skill .md files (keep consolidated + hook-equivalent)
+    for f in "$steering_dir"/atool-*.md "$steering_dir"/superpowers-*.md; do
+        [[ ! -f "$f" ]] && continue
+        local basename
+        basename=$(basename "$f")
+        # Keep consolidated files and hook-equivalent files
+        case "$basename" in
+            atool-core-workflow.md|atool-quality.md|atool-project-analyze.md|\
+            atool-office.md|atool-design.md|atool-testing.md|atool-misc.md|\
+            atool-code-review.md|atool-superpowers-advanced.md|\
+            atool-session-context.md|atool-agent-fallback.md)
+                continue ;;
+            *)
+                rm -f "$f"
+                legacy_count=$((legacy_count + 1))
+                ;;
+        esac
+    done
+
+    if [[ "$legacy_count" -gt 0 ]]; then
+        log_info "Cleaned up $legacy_count legacy per-skill steering files"
+    fi
+}
+
+# Clean up project-level .kiro/steering/ from old per-skill files
+# Args: PROJECT_STEERING_DIR
+cleanup_project_kiro_steering() {
+    local steering_dir="$1"
+    [[ ! -d "$steering_dir" ]] && return 0
+
+    local legacy_count=0
+    for f in "$steering_dir"/atool-*.md "$steering_dir"/superpowers-*.md; do
+        [[ ! -f "$f" ]] && continue
+        local basename
+        basename=$(basename "$f")
+        case "$basename" in
+            # Keep valid consolidated + hook-equivalent + conventions (template)
+            atool-core-workflow.md|atool-quality.md|atool-project-analyze.md|\
+            atool-conventions.md|\
+            atool-code-review.md|\
+            atool-office.md|atool-design.md|atool-testing.md|atool-misc.md|\
+            atool-superpowers-advanced.md|\
+            atool-session-context.md|atool-agent-fallback.md)
+                continue ;;
+            *)
+                rm -f "$f"
+                legacy_count=$((legacy_count + 1))
+                ;;
+        esac
+    done
+
+    if [[ "$legacy_count" -gt 0 ]]; then
+        log_info "Cleaned up $legacy_count legacy steering files from project"
+    fi
+
+    # Also clean up legacy .yaml files from pre-format-fix versions
+    for f in "$steering_dir"/atool-*.yaml "$steering_dir"/superpowers-*.yaml; do
+        [[ ! -f "$f" ]] && continue
+        rm -f "$f"
+        legacy_count=$((legacy_count + 1))
+    done
+}
+
+# ── Main Install ───────────────────────────────────────────────────────────
+
+install_kiro() {
+    log_step "Installing to Kiro..."
+
+    # Check if Kiro is installed
+    if ! command -v kiro &>/dev/null; then
+        local _kiro_dir
+        _kiro_dir=$(get_kiro_config_dir 2>/dev/null)
+        if [[ ! -d "$_kiro_dir" ]]; then
+            log_warn "Kiro not found in PATH and config directory does not exist"
+            log_info "Install Kiro first: https://kiro.dev"
+            if ! confirm "Continue anyway?" "N"; then
+                return 0
+            fi
+        fi
+    fi
+
+    local atool_root="${ATOOL_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
+    local atool_skills_dir="$atool_root/skills"
+    local sp_dir=""
+
+    # Kiro loads steering from PROJECT-LEVEL .kiro/steering/
+    # Global install generates steering to a staging area
+    local kiro_config_dir
+    kiro_config_dir=$(get_kiro_config_dir)
+    local staging_dir="$kiro_config_dir/steering/.atool-staging"
+
+    # 0. Clean up legacy per-skill steering files
+    cleanup_legacy_kiro_steering "$staging_dir"
+
+    # 1. Generate consolidated aTool steering
+    log_step "Generating consolidated aTool Kiro steering (staging)..."
+    if [[ -d "$atool_skills_dir" ]]; then
+        generate_consolidated_steering "$staging_dir" "get_kiro_steering_category" "$atool_skills_dir"
+    fi
+
+    # 2. Generate consolidated Superpowers steering
+    log_step "Generating consolidated Superpowers Kiro steering (staging)..."
+    local sp_submodule="$atool_root/skills/_superpowers"
+
+    if [[ -d "$sp_submodule/skills" ]]; then
+        sp_dir="$sp_submodule"
+        log_info "Using local Superpowers submodule"
+    else
+        log_warn "Superpowers submodule not found, downloading..."
+        sp_dir="$HOME/.atool/cache/superpowers"
+        download_superpowers "$sp_dir"
+    fi
+
+    if [[ -d "$sp_dir/skills" ]]; then
+        generate_consolidated_steering "$staging_dir" "get_superpowers_kiro_category" "$sp_dir/skills"
+    else
+        log_warn "Superpowers not available - skipping Superpowers steering"
+    fi
+
+    # 3. Generate hook-equivalent steering (session context + agent fallback)
+    log_step "Generating Kiro hook-equivalent steering..."
+    generate_kiro_session_context "$staging_dir" "$atool_root"
+    generate_kiro_agent_fallback "$staging_dir"
+
+    # 4. Install MCP servers (global, works for Kiro)
+    install_mcp "kiro"
+
+    log_success "Kiro installation complete!"
+    echo ""
+    log_info "Installed:"
+    log_info "  Steering (staging): $staging_dir/"
+    log_info "    - Consolidated: ~9 categorized .md files (was 43 per-skill files)"
+    log_info "    - Hook-equivalent: session context + agent fallback"
+    log_info "  MCP:               $(get_kiro_config_dir)/settings/mcp.json"
+    echo ""
+    log_warn "IMPORTANT: Kiro loads steering from PROJECT-LEVEL .kiro/steering/"
+    log_warn "Run './install.sh --project /path/to/project' to copy steering to a project."
+    log_warn "Existing files are updated via checksum comparison (no --force needed)."
+}

package/lib/install-mcp.sh

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+# aTool - lib/install-mcp.sh
+# MCP configuration installation with JSON merge
+
+set -euo pipefail
+
+# These functions are sourced by the parent script, not run directly.
+# common.sh must already be loaded.
+
+# Install MCP servers to IDE configuration
+# Args: IDE_TYPE (claude|cursor|kiro)
+install_mcp() {
+    local ide_type="$1"
+    local atool_root="${ATOOL_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
+
+    check_jq
+
+    local config_file=""
+    local mcp_key=""
+
+    case "$ide_type" in
+        claude)
+            config_file="$(get_claude_config_dir)/settings.json"
+            mcp_key=".mcpServers"
+            ;;
+        cursor)
+            config_file="$(get_cursor_config_dir)/mcp.json"
+            mcp_key=".mcpServers"
+            ;;
+        kiro)
+            config_file="$(get_kiro_config_dir)/settings/mcp.json"
+            mcp_key=".mcpServers"
+            ;;
+        *)
+            log_error "Unknown IDE type for MCP: $ide_type"
+            return 1
+            ;;
+    esac
+
+    local recommended="$atool_root/mcp/recommended.json"
+
+    if [[ ! -f "$recommended" ]]; then
+        log_error "MCP recommended config not found: $recommended"
+        return 1
+    fi
+
+    log_step "Installing MCP servers for $ide_type..."
+
+    # Ensure config directory exists
+    ensure_dir "$(dirname "$config_file")"
+
+    # Work on a temp copy to avoid corrupting the source file
+    local working_recommended
+    working_recommended=$(mktemp)
+    cp "$recommended" "$working_recommended"
+
+    if [[ -f "$config_file" ]]; then
+        # Merge: check for existing servers with same name
+        local existing_servers
+        existing_servers=$(jq -r '(.mcpServers // {}) | keys[]' "$config_file" 2>/dev/null || echo "")
+
+        local new_servers
+        new_servers=$(jq -r '(.mcpServers // {}) | keys[]' "$working_recommended" 2>/dev/null || echo "")
+
+        for server in $new_servers; do
+            if echo "$existing_servers" | grep -qx "$server"; then
+                if [[ "${ATOOL_FORCE:-0}" == "1" ]]; then
+                    log_warn "MCP server '$server' exists - overwriting (--force)"
+                else
+                    log_info "MCP server '$server' already configured - skipping (use --force to overwrite)"
+                    # Remove from working copy to avoid merging
+                    local tmp
+                    tmp=$(mktemp)
+                    jq "del(.mcpServers.\"$server\")" "$working_recommended" > "$tmp"
+                    mv "$tmp" "$working_recommended"
+                fi
+            fi
+        done
+
+        # Merge
+        backup_file "$config_file"
+        local merged
+        merged=$(json_merge "$config_file" "$working_recommended")
+
+        if ! is_dry_run; then
+            echo "$merged" | jq '.' > "$config_file"
+            log_success "MCP config merged into $config_file"
+        else
+            log_info "[DRY-RUN] Would merge MCP config into $config_file"
+        fi
+    else
+        # No existing config, just copy
+        run_cmd cp "$working_recommended" "$config_file"
+        log_success "MCP config installed to $config_file"
+    fi
+
+    # Clean up temp file
+    rm -f "$working_recommended"
+}