validate-setup.sh

#!/usr/bin/env bash
#
# Plan Forge — Setup Validator (Bash)
#
# Usage:
#   ./validate-setup.sh --path ~/projects/MyApp
#   ./validate-setup.sh            # Validates current directory
#
# Returns exit code 0 on success, 1 on failure.

set -euo pipefail

# ─── Defaults ──────────────────────────────────────────────────────────
PROJECT_PATH="$(pwd)"

# ─── Color helpers ─────────────────────────────────────────────────────
cyan()   { printf '\033[0;36m%s\033[0m\n' "$*"; }
green()  { printf '\033[0;32m%s\033[0m\n' "$*"; }
yellow() { printf '\033[0;33m%s\033[0m\n' "$*"; }
red()    { printf '\033[0;31m%s\033[0m\n' "$*"; }

# ─── Parse arguments ──────────────────────────────────────────────────
while [[ $# -gt 0 ]]; do
    case "$1" in
        --path|-p) PROJECT_PATH="$2"; shift 2 ;;
        --help|-h)
            echo "Usage: ./validate-setup.sh [--path DIR]"
            exit 0 ;;
        *) red "Unknown option: $1"; exit 1 ;;
    esac
done

PROJECT_PATH="$(cd "$PROJECT_PATH" 2>/dev/null && pwd || echo "$PROJECT_PATH")"

# ─── Counters ─────────────────────────────────────────────────────────
PASS=0
FAIL=0
WARN=0

check_file() {
    local rel_path="$1"
    local required="${2:-true}"
    local full_path="$PROJECT_PATH/$rel_path"

    if [[ -f "$full_path" ]]; then
        local size
        size="$(wc -c < "$full_path" | tr -d ' ')"
        if [[ "$size" -eq 0 ]]; then
            red "  FAIL  $rel_path (empty file)"
            if [[ "$required" == "true" ]]; then FAIL=$((FAIL+1)); else WARN=$((WARN+1)); fi
            return 1
        fi
        green "  PASS  $rel_path ($size bytes)"
        PASS=$((PASS+1))
        return 0
    else
        if [[ "$required" == "true" ]]; then
            red "  FAIL  $rel_path (missing)"
            FAIL=$((FAIL+1))
        else
            yellow "  WARN  $rel_path (missing — optional)"
            WARN=$((WARN+1))
        fi
        return 1
    fi
}

check_no_placeholders() {
    local rel_path="$1"
    local full_path="$PROJECT_PATH/$rel_path"

    [[ ! -f "$full_path" ]] && return

    local placeholders=("<YOUR PROJECT NAME>" "<YOUR TECH STACK>" "<YOUR BUILD COMMAND>" "<YOUR TEST COMMAND>" "<YOUR LINT COMMAND>")
    for ph in "${placeholders[@]}"; do
        if grep -qF "$ph" "$full_path"; then
            printf '\033[0;35m  TODO  %s contains placeholder to fill in: %s\033[0m\n' "$rel_path" "$ph"
            WARN=$((WARN+1))
        fi
    done
}

# Tool names Plan Forge itself once shipped in an agent's `tools:` list, which give the agent less in the Copilot CLI than
# the file lists. Measured with CLI 1.0.106: `editFiles` gets `edit` and no `create`; `run_in_terminal` and `read_file` get
# no shell and no search. `runCommands` and `agents` are shipped today, so they are not on this list.
agent_tool_problem() {
    case "$1" in
        editFiles)       echo "in the Copilot CLI it cannot create a file. Use 'edit'." ;;
        run_in_terminal) echo "the Copilot CLI gives the agent no shell for it. Use 'runCommands'." ;;
        read_file)       echo "the Copilot CLI has no tool of that name. Use 'read'." ;;
    esac
}

# The `tools:` entries in the first frontmatter block of an agent file, one per line: an inline list ([a, 'b']), a list in
# brackets over several lines (how Prettier writes one that is too long for a line), or a block list (- a). The key and
# the names are read as written, as validate-setup.ps1 reads them. Awk, not a pipe, so that pipefail cannot count an early
# exit as a failure; LC_ALL=C so that the byte-order mark is three plain bytes; BSD awk (macOS) and mawk read this the same
# way, so it names a bracket as a set ([[] and []]) and not as an escaped character.
agent_tool_names() {
    LC_ALL=C awk '
        function emit(s) {
            gsub(/^[ \t"\047]+/, "", s)
            gsub(/[ \t"\047]+$/, "", s)
            if (s != "") print s
        }
        # The names in a piece of a list in brackets: all of "[a, b]", or one line of a list over several lines.
        # Returns 1 when the piece ends the list. [[] and []] are the brackets as sets, which every awk reads the same way.
        function bracketed(s,    n, parts, i, closed) {
            sub(/(^|[ \t]+)#.*$/, "", s)
            sub(/^[ \t]*[[]/, "", s)
            closed = (s ~ /[]][ \t]*$/)
            sub(/[]][ \t]*$/, "", s)
            n = split(s, parts, ",")
            for (i = 1; i <= n; i++) emit(parts[i])
            return closed
        }
        function opens_bracket(s) {
            return s ~ /^[ \t]*[[]/
        }
        { sub(/\r$/, "") }
        NR == 1 { sub(/^\357\273\277/, "") }
        BEGIN { state = 0; mode = 0 }
        state == 0 {
            if ($0 ~ /^---[ \t]*$/) { state = 1; next }
            exit
        }
        /^---[ \t]*$/ { exit }
        # mode 3: inside a list in brackets that goes on over several lines.
        mode == 3 {
            if (bracketed($0)) mode = 0
            next
        }
        # mode 1: after a tools: with nothing on its line, so the list is on the lines below. mode 2: inside a block list.
        mode == 1 || mode == 2 {
            if ($0 ~ /^[ \t]*-[ \t]+/) {
                item = $0
                sub(/^[ \t]*-[ \t]+/, "", item)
                sub(/[ \t]+#.*$/, "", item)
                emit(item)
                mode = 2
                next
            }
            if ($0 ~ /^[ \t]*(#.*)?$/) next
            if (mode == 1 && opens_bracket($0)) {
                mode = bracketed($0) ? 0 : 3
                next
            }
            mode = 0
        }
        /^tools[ \t]*:/ {
            rest = $0
            sub(/^tools[ \t]*:[ \t]*/, "", rest)
            sub(/(^|[ \t]+)#.*$/, "", rest)
            sub(/[ \t]+$/, "", rest)
            if (rest == "") { mode = 1; next }
            if (opens_bracket(rest)) { if (!bracketed(rest)) mode = 3 }
            else bracketed(rest)
        }
    ' "$1"
}

# ─── Banner ────────────────────────────────────────────────────────────
echo ""
cyan "╔══════════════════════════════════════════════════════════════╗"
cyan "║       Plan Forge — Setup Validator                   ║"
cyan "╚══════════════════════════════════════════════════════════════╝"
echo ""
cyan "Validating: $PROJECT_PATH"
echo ""

# ─── Required Files ────────────────────────────────────────────────────
cyan "Required files:"

check_file ".github/copilot-instructions.md" || true
check_file ".github/instructions/architecture-principles.instructions.md" || true
check_file ".github/instructions/git-workflow.instructions.md" || true
check_file ".github/instructions/ai-plan-hardening-runbook.instructions.md" || true
check_file "docs/plans/AI-Plan-Hardening-Runbook.md" || true
check_file "docs/plans/AI-Plan-Hardening-Runbook-Instructions.md" || true
check_file "docs/plans/DEPLOYMENT-ROADMAP.md" || true

# ─── Preset-Dependent Files ───────────────────────────────────────────
echo ""
cyan "Preset-dependent files:"

CONFIG_PATH="$PROJECT_PATH/.forge.json"
if [[ -f "$CONFIG_PATH" ]]; then
    # Simple JSON parse — extract preset value
    PRESET="$(grep '"preset"' "$CONFIG_PATH" | sed 's/.*: *"\([^"]*\)".*/\1/')"
    # Treat missing/empty preset the same as 'custom' — projects that haven't
    # declared a stack preset shouldn't trigger stack-specific file checks
    # (e.g. requiring database.instructions.md on a tooling-only repo).
    if [[ -z "$PRESET" ]]; then
        cyan "  INFO  No preset declared in .forge.json — treating as 'custom'"
    else
        cyan "  INFO  Detected preset: $PRESET"
    fi

    if [[ -n "$PRESET" && "$PRESET" != "custom" ]]; then
        check_file "AGENTS.md" || true
        check_file ".github/instructions/testing.instructions.md" || true
        check_file ".github/instructions/security.instructions.md" || true

        if [[ "$PRESET" == "azure-iac" ]]; then
            # IaC-specific instruction files
            check_file ".github/instructions/bicep.instructions.md" || true
            check_file ".github/instructions/naming.instructions.md" || true
            check_file ".github/instructions/deploy.instructions.md" || true
        else
            # App-stack presets
            check_file ".github/instructions/database.instructions.md" || true
        fi
    fi

    # Check for agentic files (prompt templates, agent definitions, skills)
    echo ""
    cyan "Agentic files (prompts, agents, skills):"

    if [[ -n "$PRESET" && "$PRESET" != "custom" ]]; then
        PROMPTS_DIR="$PROJECT_PATH/.github/prompts"
        AGENTS_DIR="$PROJECT_PATH/.github/agents"
        SKILLS_DIR="$PROJECT_PATH/.github/skills"

        if [[ -d "$PROMPTS_DIR" ]]; then
            PROMPT_COUNT=$(find "$PROMPTS_DIR" -name "*.prompt.md" -type f 2>/dev/null | wc -l | tr -d ' ')
            green "  PASS  .github/prompts/ ($PROMPT_COUNT prompt templates)"
            PASS=$((PASS+1))
        else
            yellow "  WARN  .github/prompts/ (missing — optional)"
            WARN=$((WARN+1))
        fi

        if [[ -d "$AGENTS_DIR" ]]; then
            AGENT_COUNT=$(find "$AGENTS_DIR" -name "*.agent.md" -type f 2>/dev/null | wc -l | tr -d ' ')
            green "  PASS  .github/agents/ ($AGENT_COUNT agent definitions)"
            PASS=$((PASS+1))
        else
            yellow "  WARN  .github/agents/ (missing — optional)"
            WARN=$((WARN+1))
        fi

        if [[ -d "$SKILLS_DIR" ]]; then
            SKILL_COUNT=$(find "$SKILLS_DIR" -name "SKILL.md" -type f 2>/dev/null | wc -l | tr -d ' ')
            green "  PASS  .github/skills/ ($SKILL_COUNT skills)"
            PASS=$((PASS+1))
        else
            yellow "  WARN  .github/skills/ (missing — optional)"
            WARN=$((WARN+1))
        fi
    fi
else
    yellow "  WARN  .forge.json not found — skipping preset checks"
    WARN=$((WARN+1))
fi

# ─── Agent-Specific Files ─────────────────────────────────────────────
if [ -f "$CONFIG_PATH" ]; then
    # The whole quoted value, because a list such as "claude,cursor,codex" holds commas; and [[:space:]], because BSD sed
    # (macOS) has no \s.
    CONFIGURED_AGENTS="$(grep -o '"agents"[[:space:]]*:[[:space:]]*"[^"]*"' "$CONFIG_PATH" | sed 's/^"agents"[[:space:]]*:[[:space:]]*"//; s/"$//' || echo "copilot")"
    [ -z "$CONFIGURED_AGENTS" ] && CONFIGURED_AGENTS="copilot"

    IFS=',' read -ra AGENT_ARR <<< "$CONFIGURED_AGENTS"
    HAS_EXTRA=false
    for ag in "${AGENT_ARR[@]}"; do
        ag="$(echo "$ag" | tr -d ' ')"
        [ "$ag" = "copilot" ] && continue
        if [ "$HAS_EXTRA" = false ]; then
            echo ""
            cyan "Agent-specific files:"
            HAS_EXTRA=true
        fi
        case "$ag" in
            claude)
                check_file "CLAUDE.md" "false" || true
                if [ -d "$PROJECT_PATH/.claude/skills" ]; then
                    claude_count=$(find "$PROJECT_PATH/.claude/skills" -name "SKILL.md" -type f 2>/dev/null | wc -l | tr -d ' ')
                    green "  PASS  .claude/skills/ ($claude_count Claude skills)"
                    PASS=$((PASS+1))
                else
                    yellow "  WARN  .claude/skills/ (missing)"
                    WARN=$((WARN+1))
                fi
                ;;
            cursor)
                check_file ".cursor/rules" "false" || true
                if [ -d "$PROJECT_PATH/.cursor/commands" ]; then
                    cursor_count=$(find "$PROJECT_PATH/.cursor/commands" -name "*.md" -type f 2>/dev/null | wc -l | tr -d ' ')
                    green "  PASS  .cursor/commands/ ($cursor_count Cursor commands)"
                    PASS=$((PASS+1))
                else
                    yellow "  WARN  .cursor/commands/ (missing)"
                    WARN=$((WARN+1))
                fi
                ;;
            codex)
                if [ -d "$PROJECT_PATH/.agents/skills" ]; then
                    codex_count=$(find "$PROJECT_PATH/.agents/skills" -name "SKILL.md" -type f 2>/dev/null | wc -l | tr -d ' ')
                    green "  PASS  .agents/skills/ ($codex_count Codex skills)"
                    PASS=$((PASS+1))
                else
                    yellow "  WARN  .agents/skills/ (missing)"
                    WARN=$((WARN+1))
                fi
                ;;
        esac
    done
fi

# ─── Preset File Counts ───────────────────────────────────────────────
echo ""
cyan "Preset file counts:"

if [[ -f "$CONFIG_PATH" ]]; then
    PRIMARY_PRESET="$(grep '"preset"' "$CONFIG_PATH" | sed 's/.*: *"\([^"]*\)".*/\1/' | awk -F',' '{print $1}' | tr -d ' ')"

    get_min() {
        local preset="$1"
        local field="$2"
        case "$preset" in
            typescript) case "$field" in instructions) echo 18;; prompts) echo 15;; skills) echo 9;; agents) echo 6;; esac ;;
            python)     case "$field" in instructions) echo 17;; prompts) echo 15;; skills) echo 9;; agents) echo 6;; esac ;;
            dotnet)     case "$field" in instructions) echo 17;; prompts) echo 15;; skills) echo 9;; agents) echo 6;; esac ;;
            go)         case "$field" in instructions) echo 17;; prompts) echo 15;; skills) echo 9;; agents) echo 6;; esac ;;
            java)       case "$field" in instructions) echo 17;; prompts) echo 15;; skills) echo 9;; agents) echo 6;; esac ;;
            rust)       case "$field" in instructions) echo 17;; prompts) echo 15;; skills) echo 9;; agents) echo 6;; esac ;;
            swift)      case "$field" in instructions) echo 16;; prompts) echo 13;; skills) echo 9;; agents) echo 6;; esac ;;
            php)        case "$field" in instructions) echo 17;; prompts) echo 15;; skills) echo 9;; agents) echo 6;; esac ;;
            azure-iac)  case "$field" in instructions) echo 12;; prompts) echo 6;;  skills) echo 3;; agents) echo 5;; esac ;;
            *) echo "" ;;
        esac
    }

    MIN_INSTR="$(get_min "$PRIMARY_PRESET" instructions)"
    if [[ -n "$MIN_INSTR" && "$PRIMARY_PRESET" != "custom" ]]; then
        MIN_PROMPTS="$(get_min "$PRIMARY_PRESET" prompts)"
        MIN_SKILLS="$(get_min "$PRIMARY_PRESET" skills)"
        MIN_AGENTS="$(get_min "$PRIMARY_PRESET" agents)"

        ACTUAL_INSTR=$(find "$PROJECT_PATH/.github/instructions" -maxdepth 1 -name "*.instructions.md" -type f 2>/dev/null | wc -l | tr -d ' ')
        ACTUAL_PROMPTS=$(find "$PROJECT_PATH/.github/prompts" -maxdepth 1 -name "*.prompt.md" -type f 2>/dev/null | wc -l | tr -d ' ')
        ACTUAL_SKILLS=$(find "$PROJECT_PATH/.github/skills" -name "SKILL.md" -type f 2>/dev/null | wc -l | tr -d ' ')
        ACTUAL_AGENTS=$(find "$PROJECT_PATH/.github/agents" -maxdepth 1 -name "*.agent.md" -type f 2>/dev/null | wc -l | tr -d ' ')

        check_count() {
            local label="$1" actual="$2" min="$3" name="$4"
            if [[ "$actual" -ge "$min" ]]; then
                green "  PASS  $label — $actual $name (min: $min)"
                PASS=$((PASS+1))
            else
                red "  FAIL  $label — $actual $name (expected ≥ $min for '$PRIMARY_PRESET' preset)"
                FAIL=$((FAIL+1))
            fi
        }

        check_count ".github/instructions/" "$ACTUAL_INSTR"   "$MIN_INSTR"    "instruction files"
        check_count ".github/prompts/"      "$ACTUAL_PROMPTS" "$MIN_PROMPTS"  "prompt templates"
        check_count ".github/skills/"       "$ACTUAL_SKILLS"  "$MIN_SKILLS"   "skills"
        check_count ".github/agents/"       "$ACTUAL_AGENTS"  "$MIN_AGENTS"   "agent definitions"
    elif [[ "$PRIMARY_PRESET" == "custom" || -z "$PRIMARY_PRESET" ]]; then
        cyan "  INFO  Custom preset — skipping minimum count checks"
    else
        yellow "  WARN  Unknown preset '$PRIMARY_PRESET' — skipping minimum count checks"
        WARN=$((WARN+1))
    fi
else
    yellow "  WARN  .forge.json not found — skipping minimum count checks"
    WARN=$((WARN+1))
fi

# ─── Agent Tool Names ─────────────────────────────────────────────────
# `pforge update` keeps an agent file you edited, so a copy from before a fix still lists the old name.
AGENT_TOOL_FILES=()
if [[ -d "$PROJECT_PATH/.github/agents" ]]; then
    while IFS= read -r agent_file; do
        AGENT_TOOL_FILES+=("$agent_file")
    done < <(find "$PROJECT_PATH/.github/agents" -maxdepth 1 -name "*.agent.md" -type f 2>/dev/null | sort)
fi

# ${#array[@]} is safe on an empty array; expanding "${array[@]}" under set -u is not, in Bash before 4.4 (macOS ships 3.2).
if [[ ${#AGENT_TOOL_FILES[@]} -gt 0 ]]; then
    echo ""
    cyan "Agent tool names:"

    tool_warnings=0
    for agent_file in "${AGENT_TOOL_FILES[@]}"; do
        while IFS= read -r tool_name; do
            [[ -z "$tool_name" ]] && continue
            tool_problem="$(agent_tool_problem "$tool_name")"
            if [[ -n "$tool_problem" ]]; then
                yellow "  WARN  .github/agents/$(basename "$agent_file") lists '$tool_name': $tool_problem"
                WARN=$((WARN+1))
                tool_warnings=$((tool_warnings+1))
            fi
        done < <(agent_tool_names "$agent_file")
    done

    if [[ "$tool_warnings" -eq 0 ]]; then
        green "  PASS  .github/agents/ tool names (${#AGENT_TOOL_FILES[@]} agent files, none that fails in the Copilot CLI)"
        PASS=$((PASS+1))
    else
        cyan "  INFO  pforge update replaces an agent file you have not edited; one you edited is kept, with the new copy under .forge/update-pending/"
    fi
fi

# ─── Optional Files ───────────────────────────────────────────────────
echo ""
cyan "Optional files:"

check_file ".vscode/settings.json" "false" || true
check_file "docs/COPILOT-VSCODE-GUIDE.md" "false" || true
check_file ".forge.json" "false" || true

# ─── New Capabilities (Optional) ──────────────────────────────────────
echo ""
cyan "Optional capabilities:"

# Project Principles
PP_PATH="$PROJECT_PATH/docs/plans/PROJECT-PRINCIPLES.md"
if [[ -f "$PP_PATH" ]]; then
    PP_COUNT=$(grep -cE '^\|[[:space:]]*[0-9]+[[:space:]]*\|' "$PP_PATH" 2>/dev/null || echo "0")
    green "  PASS  Project Principles: found ($PP_COUNT principles)"
    PASS=$((PASS+1))
else
    yellow "  WARN  Project Principles: not created (optional — run project-principles.prompt.md)"
    WARN=$((WARN+1))
fi

# Extensions
EXT_JSON="$PROJECT_PATH/.forge/extensions/extensions.json"
if [[ -f "$EXT_JSON" ]]; then
    # Node, not python3: Windows' Git Bash finds the Microsoft Store python3 stub, which cannot run (#394).
    EXT_COUNT=$(node -e "const e = JSON.parse(require('fs').readFileSync(process.argv[1], 'utf8').replace(/^\uFEFF/, '')).extensions; console.log(Array.isArray(e) ? e.length : 0)" "$EXT_JSON" 2>/dev/null || echo "0")
    if [[ "$EXT_COUNT" -gt 0 ]]; then
        green "  PASS  Extensions: $EXT_COUNT installed"
        PASS=$((PASS+1))
    else
        yellow "  WARN  Extensions: none installed (optional)"
        WARN=$((WARN+1))
    fi
else
    yellow "  WARN  Extensions: not configured (optional)"
    WARN=$((WARN+1))
fi

# CLI
if [[ -f "$PROJECT_PATH/pforge.sh" ]] || [[ -f "$PROJECT_PATH/pforge.ps1" ]]; then
    green "  PASS  CLI: pforge script found"
    PASS=$((PASS+1))
else
    yellow "  WARN  CLI: pforge not installed (optional)"
    WARN=$((WARN+1))
fi

# ─── Plan Forge Runtime (Optional) ────────────────────────────────────
echo ""
cyan "Plan Forge runtime:"

# VERSION file
if [[ -f "$PROJECT_PATH/VERSION" ]]; then
    VER="$(tr -d ' \t\r\n' < "$PROJECT_PATH/VERSION")"
    green "  PASS  VERSION: v$VER"
    PASS=$((PASS+1))
else
    yellow "  WARN  VERSION: not found (optional — only required in Plan Forge source repo)"
    WARN=$((WARN+1))
fi

# MCP server
if [[ -f "$PROJECT_PATH/pforge-mcp/server.mjs" ]] && [[ -f "$PROJECT_PATH/pforge-mcp/package.json" ]]; then
    MCP_VER="$(grep -oE '"version"[[:space:]]*:[[:space:]]*"[^"]+"' "$PROJECT_PATH/pforge-mcp/package.json" | head -1 | sed -E 's/.*"([^"]+)"$/\1/')"
    if [[ -d "$PROJECT_PATH/pforge-mcp/node_modules" ]]; then
        green "  PASS  MCP server: pforge-mcp v${MCP_VER} (deps installed)"
    else
        yellow "  WARN  MCP server: pforge-mcp v${MCP_VER} — run 'npm install' in pforge-mcp/"
        WARN=$((WARN+1))
    fi
    PASS=$((PASS+1))
else
    yellow "  WARN  MCP server: pforge-mcp/ not found (optional — only required in Plan Forge source repo)"
    WARN=$((WARN+1))
fi

# Forge-Master Studio (Phase-29 chat bridge — imported by pforge-mcp via
# relative paths and registered as second MCP server in .vscode/mcp.json)
if [[ -f "$PROJECT_PATH/pforge-master/server.mjs" ]] && [[ -f "$PROJECT_PATH/pforge-master/package.json" ]]; then
    FM_VER="$(grep -oE '"version"[[:space:]]*:[[:space:]]*"[^"]+"' "$PROJECT_PATH/pforge-master/package.json" | head -1 | sed -E 's/.*"([^"]+)"$/\1/')"
    if [[ -d "$PROJECT_PATH/pforge-master/node_modules" ]]; then
        green "  PASS  Forge-Master: pforge-master v${FM_VER} (deps installed)"
    else
        yellow "  WARN  Forge-Master: pforge-master v${FM_VER} — run 'npm install' in pforge-master/"
        WARN=$((WARN+1))
    fi
    PASS=$((PASS+1))
else
    yellow "  WARN  Forge-Master: pforge-master/ not found (optional — chat bridge unavailable)"
    WARN=$((WARN+1))
fi

# A file: dependency in a framework package, and the link it leaves in node_modules, come from an older installer that
# ran `npm install --prefix` from a directory with its own package.json (#422). Nothing in Plan Forge depends on a
# folder outside the package, and `pforge update --force` installs the shipped dependencies, which removes both (#428).
# Node reads the same three sections validate-setup.ps1 does, and sees an NTFS junction as a link, which `[[ -L ]]` in
# Git Bash does not; without node, any file: or link: value in the manifest counts and only a symbolic link does.
LEFT_BEHIND_JS='
const fs = require("fs");
const [manifest, stale] = process.argv.slice(1);
const found = [];
try {
  const parsed = JSON.parse(fs.readFileSync(manifest, "utf8").replace(/^\uFEFF/, ""));
  const sections = ["dependencies", "devDependencies", "optionalDependencies"];
  if (sections.some((name) => Object.values(parsed[name] ?? {}).some((spec) => /^(file|link):/.test(spec)))) found.push("package.json has a file: dependency");
} catch {}
try {
  if (fs.lstatSync(stale).isSymbolicLink()) found.push("node_modules/plan-forge is a link to another folder");
} catch {}
process.stdout.write(found.join("; "));
'
for FRAMEWORK_PACKAGE in pforge-mcp pforge-master; do
    FRAMEWORK_MANIFEST="$PROJECT_PATH/$FRAMEWORK_PACKAGE/package.json"
    [[ -f "$FRAMEWORK_MANIFEST" ]] || continue
    STALE_LINK="$PROJECT_PATH/$FRAMEWORK_PACKAGE/node_modules/plan-forge"
    LEFT_BEHIND=""
    if command -v node >/dev/null 2>&1; then
        LEFT_BEHIND="$(node -e "$LEFT_BEHIND_JS" "$FRAMEWORK_MANIFEST" "$STALE_LINK" 2>/dev/null || true)"
    else
        if grep -qE '"[^"]+"[[:space:]]*:[[:space:]]*"(file|link):' "$FRAMEWORK_MANIFEST"; then
            LEFT_BEHIND="package.json has a file: dependency"
        fi
        if [[ -L "$STALE_LINK" ]]; then
            LEFT_BEHIND="${LEFT_BEHIND:+$LEFT_BEHIND; }node_modules/plan-forge is a link to another folder"
        fi
    fi
    if [[ -n "$LEFT_BEHIND" ]]; then
        yellow "  WARN  ${FRAMEWORK_PACKAGE}: ${LEFT_BEHIND}, left by an older installer. Run 'pforge update --force' to repair it"
        WARN=$((WARN+1))
    fi
done

# pforge-sdk (shared helper library — NO runtime deps, imported via
# relative paths from pforge-mcp; missing files crash opt-in features)
if [[ -f "$PROJECT_PATH/pforge-sdk/src/client.mjs" ]]; then
    green "  PASS  pforge-sdk: src/client.mjs found"
    PASS=$((PASS+1))
else
    yellow "  WARN  pforge-sdk: src/client.mjs not found (deep imports from pforge-mcp will fail)"
    WARN=$((WARN+1))
fi

# .vscode/mcp.json with plan-forge entry
if [[ -f "$PROJECT_PATH/.vscode/mcp.json" ]]; then
    if grep -qE '"(plan-forge|pforge)"' "$PROJECT_PATH/.vscode/mcp.json"; then
        green "  PASS  .vscode/mcp.json: plan-forge server configured"
        PASS=$((PASS+1))
    else
        yellow "  WARN  .vscode/mcp.json: no plan-forge server entry (run setup.sh to wire)"
        WARN=$((WARN+1))
    fi
else
    yellow "  WARN  .vscode/mcp.json: not configured (optional)"
    WARN=$((WARN+1))
fi

# Dashboard (served by MCP server on :3100/dashboard)
if [[ -f "$PROJECT_PATH/pforge-mcp/dashboard/index.html" ]]; then
    green "  PASS  Dashboard: pforge-mcp/dashboard/ found"
    PASS=$((PASS+1))
else
    yellow "  WARN  Dashboard: pforge-mcp/dashboard/ not found (optional)"
    WARN=$((WARN+1))
fi

# ─── Placeholder Scan ─────────────────────────────────────────────────
echo ""
cyan "Placeholder scan:"

check_no_placeholders ".github/copilot-instructions.md"
check_no_placeholders "AGENTS.md"
check_no_placeholders "docs/plans/DEPLOYMENT-ROADMAP.md"

# ─── Summary ──────────────────────────────────────────────────────────
echo ""
echo "────────────────────────────────────────────────────"
if [[ $FAIL -gt 0 ]]; then
    red "  Results:  $PASS passed  |  $FAIL failed  |  $WARN warnings"
else
    green "  Results:  $PASS passed  |  $FAIL failed  |  $WARN warnings"
fi
echo "────────────────────────────────────────────────────"

if [[ $FAIL -gt 0 ]]; then
    echo ""
    red "VALIDATION FAILED"
    red "Fix the $FAIL failed check(s) above before proceeding."
    exit 1
else
    echo ""
    green "VALIDATION PASSED"
    if [[ $WARN -gt 0 ]]; then
        yellow "$WARN warning(s) — review optional items above."
    fi
    exit 0
fi