@lvlup-sw/exarchos 2.0.1

package/scripts/static-analysis-gate.sh

@@ -0,0 +1,236 @@
+#!/usr/bin/env bash
+# Static Analysis Gate
+# Runs static analysis tools with structured pass/fail output for the quality-review workflow.
+#
+# Usage: static-analysis-gate.sh --repo-root <path> [--skip-lint] [--skip-typecheck]
+#
+# Exit codes:
+#   0 = all checks pass (warnings OK)
+#   1 = errors found
+#   2 = usage error
+
+set -euo pipefail
+
+# ============================================================
+# ARGUMENT PARSING
+# ============================================================
+
+REPO_ROOT=""
+SKIP_LINT=false
+SKIP_TYPECHECK=false
+
+usage() {
+    cat << 'USAGE'
+Usage: static-analysis-gate.sh --repo-root <path> [--skip-lint] [--skip-typecheck]
+
+Run static analysis tools with structured pass/fail output.
+
+Required:
+  --repo-root <path>    Repository root containing package.json
+
+Optional:
+  --skip-lint           Skip lint check
+  --skip-typecheck      Skip typecheck
+  --help                Show this help message
+
+Exit codes:
+  0  All checks pass (warnings OK)
+  1  Errors found in one or more tools
+  2  Usage error (missing required args)
+USAGE
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --repo-root)
+            if [[ -z "${2:-}" ]]; then
+                echo "Error: --repo-root requires a path argument" >&2
+                exit 2
+            fi
+            REPO_ROOT="$2"
+            shift 2
+            ;;
+        --skip-lint)
+            SKIP_LINT=true
+            shift
+            ;;
+        --skip-typecheck)
+            SKIP_TYPECHECK=true
+            shift
+            ;;
+        --help)
+            usage
+            exit 0
+            ;;
+        *)
+            echo "Error: Unknown argument '$1'" >&2
+            usage >&2
+            exit 2
+            ;;
+    esac
+done
+
+if [[ -z "$REPO_ROOT" ]]; then
+    echo "Error: --repo-root is required" >&2
+    usage >&2
+    exit 2
+fi
+
+if [[ ! -f "$REPO_ROOT/package.json" ]]; then
+    echo "Error: No package.json found at $REPO_ROOT" >&2
+    exit 2
+fi
+
+# ============================================================
+# CHECK FUNCTIONS
+# ============================================================
+
+CHECK_PASS=0
+CHECK_FAIL=0
+RESULTS=()
+
+check_pass() {
+    local name="$1"
+    local detail="${2:-}"
+    if [[ -n "$detail" ]]; then
+        RESULTS+=("- **PASS**: $name — $detail")
+    else
+        RESULTS+=("- **PASS**: $name")
+    fi
+    CHECK_PASS=$((CHECK_PASS + 1))
+}
+
+check_fail() {
+    local name="$1"
+    local detail="${2:-}"
+    if [[ -n "$detail" ]]; then
+        RESULTS+=("- **FAIL**: $name — $detail")
+    else
+        RESULTS+=("- **FAIL**: $name")
+    fi
+    CHECK_FAIL=$((CHECK_FAIL + 1))
+}
+
+check_skip() {
+    local name="$1"
+    local detail="${2:-}"
+    if [[ -n "$detail" ]]; then
+        RESULTS+=("- **SKIP**: $name — $detail")
+    else
+        RESULTS+=("- **SKIP**: $name")
+    fi
+}
+
+# Check if an npm script exists in package.json
+has_npm_script() {
+    local script_name="$1"
+    node -e '
+        const p = require(process.argv[1]);
+        const s = p.scripts || {};
+        process.exit(s[process.argv[2]] ? 0 : 1);
+    ' "$REPO_ROOT/package.json" "$script_name" 2>/dev/null
+}
+
+# ============================================================
+# CHECK 1: Lint
+# ============================================================
+
+run_lint() {
+    if [[ "$SKIP_LINT" == true ]]; then
+        check_skip "Lint" "--skip-lint"
+        return 0
+    fi
+
+    if ! has_npm_script "lint"; then
+        check_skip "Lint" "no 'lint' script in package.json"
+        return 0
+    fi
+
+    local output
+    if output="$(cd "$REPO_ROOT" && npm run lint 2>&1)"; then
+        check_pass "Lint"
+        return 0
+    else
+        check_fail "Lint" "npm run lint failed"
+        return 1
+    fi
+}
+
+# ============================================================
+# CHECK 2: Typecheck
+# ============================================================
+
+run_typecheck() {
+    if [[ "$SKIP_TYPECHECK" == true ]]; then
+        check_skip "Typecheck" "--skip-typecheck"
+        return 0
+    fi
+
+    if ! has_npm_script "typecheck"; then
+        check_skip "Typecheck" "no 'typecheck' script in package.json"
+        return 0
+    fi
+
+    local output
+    if output="$(cd "$REPO_ROOT" && npm run typecheck 2>&1)"; then
+        check_pass "Typecheck"
+        return 0
+    else
+        check_fail "Typecheck" "npm run typecheck failed"
+        return 1
+    fi
+}
+
+# ============================================================
+# CHECK 3: Quality check
+# ============================================================
+
+run_quality_check() {
+    if ! has_npm_script "quality-check"; then
+        check_skip "Quality check" "no 'quality-check' script in package.json"
+        return 0
+    fi
+
+    local output
+    if output="$(cd "$REPO_ROOT" && npm run quality-check 2>&1)"; then
+        check_pass "Quality check"
+        return 0
+    else
+        check_fail "Quality check" "npm run quality-check failed"
+        return 1
+    fi
+}
+
+# ============================================================
+# EXECUTE CHECKS
+# ============================================================
+
+run_lint || true
+run_typecheck || true
+run_quality_check || true
+
+# ============================================================
+# STRUCTURED OUTPUT
+# ============================================================
+
+echo "## Static Analysis Report"
+echo ""
+echo "**Repository:** \`$REPO_ROOT\`"
+echo ""
+
+for result in "${RESULTS[@]}"; do
+    echo "$result"
+done
+
+echo ""
+TOTAL=$((CHECK_PASS + CHECK_FAIL))
+echo "---"
+echo ""
+
+if [[ $CHECK_FAIL -eq 0 ]]; then
+    echo "**Result: PASS** ($CHECK_PASS/$TOTAL checks passed)"
+    exit 0
+else
+    echo "**Result: FAIL** ($CHECK_FAIL/$TOTAL checks failed)"
+    exit 1
+fi

package/scripts/sync-labels.sh

@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+# sync-labels.sh - Sync labels from .github/labels.yml to GitHub
+#
+# Usage: ./scripts/sync-labels.sh [--dry-run]
+#
+# Requires: gh (GitHub CLI), python3 with pyyaml
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(dirname "$SCRIPT_DIR")"
+LABELS_FILE="$REPO_ROOT/.github/labels.yml"
+
+# Auto-detect repository from git remote, environment, or use default
+if [[ -n "${GITHUB_REPOSITORY:-}" ]]; then
+    # Use GitHub Actions environment variable
+    REPO="$GITHUB_REPOSITORY"
+elif command -v gh &> /dev/null && gh repo view --json nameWithOwner -q .nameWithOwner &> /dev/null; then
+    # Auto-detect from git remote via gh CLI
+    REPO="$(gh repo view --json nameWithOwner -q .nameWithOwner)"
+else
+    # Fallback to default
+    REPO="lvlup-sw/exarchos"
+fi
+
+# Parse arguments
+DRY_RUN=false
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --dry-run) DRY_RUN=true; shift ;;
+        -h|--help)
+            echo "Usage: $0 [--dry-run]"
+            echo ""
+            echo "Options:"
+            echo "  --dry-run  Show what would be done without making changes"
+            echo "  -h, --help Show this help message"
+            exit 0
+            ;;
+        *)
+            echo "Error: Unknown argument: $1" >&2
+            echo "Use --help for usage information" >&2
+            exit 1
+            ;;
+    esac
+done
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+info() { echo -e "${GREEN}[INFO]${NC} $1"; }
+warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }
+error() { echo -e "${RED}[ERROR]${NC} $1"; exit 1; }
+
+# Check dependencies
+check_deps() {
+    if ! command -v gh &> /dev/null; then
+        error "gh (GitHub CLI) is required but not installed"
+    fi
+    if ! python3 -c "import yaml" &> /dev/null; then
+        error "Python yaml module is required. Install with: pip install pyyaml"
+    fi
+    if [[ ! -f "$LABELS_FILE" ]]; then
+        error "Labels file not found: $LABELS_FILE"
+    fi
+}
+
+# Delete default GitHub labels we don't use
+delete_default_labels() {
+    local defaults=("duplicate" "enhancement" "good first issue" "help wanted" "invalid" "wontfix" "bug" "documentation" "question")
+
+    info "Removing default labels..."
+    for label in "${defaults[@]}"; do
+        if [[ "$DRY_RUN" == "true" ]]; then
+            echo "  [dry-run] Would delete: $label"
+        else
+            gh label delete "$label" -R "$REPO" --yes 2>/dev/null && \
+                echo "  Deleted: $label" || \
+                echo "  Skipped: $label (not found)"
+        fi
+    done
+}
+
+# Create/update labels from config
+sync_labels() {
+    info "Syncing labels from $LABELS_FILE..."
+
+    # Parse YAML and create labels using Python
+    python3 -c "import yaml; [print(f\"{l['name']}|{l['color']}|{l['description']}\") for l in yaml.safe_load(open('$LABELS_FILE'))]" | \
+    while IFS='|' read -r name color desc; do
+        if [[ "$DRY_RUN" == "true" ]]; then
+            echo "  [dry-run] Would create/update: $name ($color) - $desc"
+        else
+            gh label create "$name" -R "$REPO" --color "$color" --description "$desc" --force 2>/dev/null && \
+                echo "  Created/Updated: $name" || \
+                echo "  Failed: $name"
+        fi
+    done
+}
+
+# Main
+main() {
+    echo "Label Sync"
+    echo "=========="
+    echo ""
+    echo "Repository: $REPO"
+    echo "Labels file: $LABELS_FILE"
+    [[ "$DRY_RUN" == "true" ]] && echo "Mode: DRY RUN"
+    echo ""
+
+    check_deps
+    delete_default_labels
+    echo ""
+    sync_labels
+
+    echo ""
+    info "Label sync complete!"
+}
+
+main

package/scripts/validate-companion.sh

@@ -0,0 +1,161 @@
+#!/usr/bin/env bash
+# validate-companion.sh — Validate companion plugin directory structure
+#
+# Checks:
+#   1. companion/.claude-plugin/plugin.json exists and valid JSON with required fields (name, version, mcpServers)
+#   2. companion/.mcp.json exists and valid JSON
+#   3. companion/settings.json exists and valid JSON with enabledPlugins
+#
+# Usage: validate-companion.sh --repo-root <path>
+#
+# Exit codes:
+#   0 = all checks pass
+#   1 = one or more checks fail
+#   2 = usage error
+
+set -euo pipefail
+
+# ============================================================
+# ARGUMENT PARSING
+# ============================================================
+
+REPO_ROOT="."
+
+usage() {
+  cat << 'USAGE'
+Usage: validate-companion.sh --repo-root <path>
+
+Validates the Exarchos companion plugin directory structure.
+
+Options:
+  --repo-root <path>   Path to the repository root (default: .)
+  --help               Show this help message
+
+Exit codes:
+  0  All checks pass
+  1  One or more checks fail
+  2  Usage error
+USAGE
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --repo-root)
+      if [[ -z "${2:-}" ]]; then
+        echo "Error: --repo-root requires a path argument" >&2
+        exit 2
+      fi
+      REPO_ROOT="$2"
+      shift 2
+      ;;
+    --help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "Error: Unknown argument '$1'" >&2
+      usage >&2
+      exit 2
+      ;;
+  esac
+done
+
+if [[ ! -d "$REPO_ROOT" ]]; then
+  echo "Error: Repository root not found: $REPO_ROOT" >&2
+  exit 2
+fi
+
+# ============================================================
+# DEPENDENCY CHECK
+# ============================================================
+
+if ! command -v jq &>/dev/null; then
+  echo "Error: jq is required but not installed" >&2
+  exit 2
+fi
+
+# ============================================================
+# VALIDATION
+# ============================================================
+
+CHECK_PASS=0
+CHECK_FAIL=0
+TOTAL=0
+RESULTS=()
+
+check() {
+  local description="$1"
+  local passed="$2"
+  TOTAL=$((TOTAL + 1))
+  if [[ "$passed" == "true" ]]; then
+    RESULTS+=("- **PASS**: $description")
+    CHECK_PASS=$((CHECK_PASS + 1))
+  else
+    RESULTS+=("- **FAIL**: $description")
+    CHECK_FAIL=$((CHECK_FAIL + 1))
+  fi
+}
+
+# --- Check 1: companion/.claude-plugin/plugin.json exists and valid JSON with required fields ---
+PLUGIN_JSON="$REPO_ROOT/companion/.claude-plugin/plugin.json"
+if [[ -f "$PLUGIN_JSON" ]] && jq empty "$PLUGIN_JSON" 2>/dev/null; then
+  REQUIRED_FIELDS=("name" "version" "mcpServers")
+  ALL_FIELDS_PRESENT=true
+  MISSING_FIELDS=()
+  for field in "${REQUIRED_FIELDS[@]}"; do
+    if ! jq -e ".$field" "$PLUGIN_JSON" >/dev/null 2>&1; then
+      ALL_FIELDS_PRESENT=false
+      MISSING_FIELDS+=("$field")
+    fi
+  done
+  if [[ "$ALL_FIELDS_PRESENT" == "true" ]]; then
+    check "companion/.claude-plugin/plugin.json exists and valid" "true"
+  else
+    check "companion/.claude-plugin/plugin.json missing fields: ${MISSING_FIELDS[*]}" "false"
+  fi
+else
+  check "companion/.claude-plugin/plugin.json exists and valid" "false"
+fi
+
+# --- Check 2: companion/.mcp.json exists and valid JSON ---
+MCP_FILE="$REPO_ROOT/companion/.mcp.json"
+if [[ -f "$MCP_FILE" ]] && jq empty "$MCP_FILE" 2>/dev/null; then
+  check "companion/.mcp.json exists and valid JSON" "true"
+else
+  check "companion/.mcp.json exists and valid JSON" "false"
+fi
+
+# --- Check 3: companion/settings.json exists and valid JSON with enabledPlugins ---
+SETTINGS_FILE="$REPO_ROOT/companion/settings.json"
+if [[ -f "$SETTINGS_FILE" ]] && jq empty "$SETTINGS_FILE" 2>/dev/null; then
+  if jq -e '.enabledPlugins' "$SETTINGS_FILE" >/dev/null 2>&1; then
+    check "companion/settings.json exists and has enabledPlugins" "true"
+  else
+    check "companion/settings.json missing enabledPlugins field" "false"
+  fi
+else
+  check "companion/settings.json exists and valid JSON" "false"
+fi
+
+# ============================================================
+# STRUCTURED OUTPUT
+# ============================================================
+
+echo "## Companion Validation Report"
+echo ""
+
+for result in "${RESULTS[@]}"; do
+  echo "$result"
+done
+
+echo ""
+echo "---"
+echo ""
+
+if [[ $CHECK_FAIL -eq 0 ]]; then
+  echo "**Result: PASS** ($CHECK_PASS/$TOTAL checks passed)"
+  exit 0
+else
+  echo "**Result: FAIL** ($CHECK_PASS/$TOTAL checks passed)"
+  exit 1
+fi