Taskfile.yml

version: '3'

silent: true
dotenv: ['.env']

vars:
  ENV_FILE: '.env'
  COMPOSE_FILE: '.devcontainer/docker-compose.yml'
  SPLUNK_SERVICE: 'splunk'
  CONFIG_APPS_DIR: 'splunk/config/apps'
  DEPS_FILE: 'splunk/config/deps.yml'
  COMPOSE_STAGING_FILE: '.devcontainer/docker-compose.staging.yml'
  STAGE_DIR: 'splunk/stage'
  SPLUNK_BIN: '/opt/splunk/bin/splunk'
  SPLUNK_CONTAINER: 'splunk-dev'
  STAGING_CONTAINER: 'splunk-staging'
  STAGING_SERVICE: 'splunk-staging'
  REACT_PACKAGES_DIR: 'react'
  UCC_SRC_DIR: 'ucc'
  UCC_OUTPUT_DIR: 'ucc/output'

tasks:
  default:
    cmds:
      - task help
    desc: Show available tasks

  help:
    cmds:
      - |
        echo ""
        echo "Splunk Dev Container — task runner"
        echo "=================================="
        task --list
        echo ""
        echo "Dev environment (port 8000):"
        echo "  task dev:build-image        # build dev Splunk Docker image (first time / Dockerfile change)"
        echo "  task dev:up                 # start + sync app symlinks (no rebuild)"
        echo "  task dev:refresh            # reload configs + static assets (no restart)"
        echo "  task dev:restartd           # restart splunkd process (~10s)"
        echo "  task dev:restart            # restart container (skips Ansible)"
        echo "  task dev:reprovision        # force full Ansible re-provisioning"
        echo "  task dev:ensure-links       # sync app symlinks (idempotent, run after dev:clean)"
        echo "  task dev:clean              # stop + remove volumes (full reset)"
        echo ""
        echo "App development:"
        echo "  task app:create APP_NAME=x  # scaffold a new Splunk app"
        echo "  task app:package APP_NAME=x # package app dir into splunk/stage/<APP>.tgz"
        echo "  task deps:install           # install Splunkbase dependencies into dev container"
        echo ""
        echo "React development:"
        echo "  task react:create                      # interactive, or APP_NAME=x for non-interactive"
        echo "  task react:add-page                    # interactive, or PAGE_NAME=x APP_NAME=y"
        echo "  task react:add-component               # interactive, or COMPONENT_NAME=x [COMPONENT_TYPE=basic|dashboard]"
        echo "  task react:link             # symlink stage/ into dev Splunk (run once)"
        echo "  task react:start            # webpack watch (stage/ updates live via symlink)"
        echo "  task react:build            # production webpack build (rebuilds stage/)"
        echo "  task react:package          # build + package React app into splunk/stage/<APP>.tgz"
        echo ""
        echo "UCC add-on development:"
        echo "  task ucc:init APP_NAME=x    # scaffold UCC add-on (globalConfig.json + package/)"
        echo "  task ucc:add-react          # add React UI to UCC app (scaffold + adapt + build)"
        echo "  task ucc:build              # run ucc-gen build (generates UI, REST, conf)"
        echo "  task ucc:link               # symlink build output into dev Splunk"
        echo "  task ucc:dev                # build + link + refresh (fast iteration loop)"
        echo "  task ucc:package            # build + package to splunk/stage/"
        echo "  task ucc:appinspect         # run Splunk AppInspect (precert mode)"
        echo ""
        echo "Staging environment (port 18000):"
        echo "  task stage:deploy           # package + start + install (full pipeline)"
        echo "  task stage:package          # package all apps to splunk/stage/"
        echo "  task stage:up               # start staging container"
        echo "  task stage:install          # install tgz into running staging"
        echo "  task stage:down             # stop staging container"
        echo "  task stage:clean            # stop staging + remove volumes"
    desc: Show available tasks and common flows

  # ── Internal helpers ─────────────────────────────────────────────────

  __dev-compose:
    internal: true
    cmds:
      - docker compose --env-file {{.ENV_FILE}} -f {{.COMPOSE_FILE}} {{.COMPOSE_ARGS}}

  __stage-compose:
    internal: true
    cmds:
      - docker compose --env-file {{.ENV_FILE}} -f {{.COMPOSE_STAGING_FILE}} {{.COMPOSE_ARGS}}

  __dev:ensure-running:
    internal: true
    cmds:
      - |
        if ! docker ps --filter name="{{.SPLUNK_CONTAINER}}" --format '{{`{{.Names}}`}}' | grep -q "^{{.SPLUNK_CONTAINER}}$"; then
          echo "ERROR: Dev container is not running. Start with: task dev:up"
          exit 1
        fi

  __stage:ensure-running:
    internal: true
    cmds:
      - |
        if ! docker ps --filter name="{{.STAGING_CONTAINER}}" --format '{{`{{.Names}}`}}' | grep -q "^{{.STAGING_CONTAINER}}$"; then
          echo "ERROR: Staging container is not running. Start with: task stage:up"
          exit 1
        fi

  __ensure-image:
    internal: true
    cmds:
      - |
        if ! docker images -q devcontainer-splunk:latest 2>/dev/null | grep -q .; then
          echo "ERROR: Splunk image not built. Run: task dev:build-image"
          exit 1
        fi

  __wait-healthy:
    internal: true
    cmds:
      - |
        echo "Waiting for {{.WAIT_CONTAINER}} to be ready..."
        for i in $(seq 1 36); do
          STATUS=$(docker exec {{.WAIT_CONTAINER}} bash -lc \
            "curl -sk -o /dev/null -w '%{http_code}' https://localhost:8089/services/server/health -u admin:\$SPLUNK_PASSWORD" 2>/dev/null || echo 000)
          [ "$STATUS" = "200" ] && echo "{{.WAIT_CONTAINER}} ready." && exit 0
          [ "$i" = "36" ] && echo "{{.WAIT_CONTAINER}} did not become ready in time." && exit 1
          sleep 5
        done

  __ensure-app-name:
    internal: true
    cmds:
      - |
        if [ -z "{{.APP_NAME}}" ]; then
          echo "ERROR: APP_NAME is required (pass APP_NAME=x or set in .env)"
          exit 1
        fi

  # ── Dev Splunk Lifecycle ────────────────────────────────────────────

  dev:build-image:
    cmds:
      - task: __dev-compose
        vars: { COMPOSE_ARGS: 'build {{.SPLUNK_SERVICE}}' }
    desc: Build the dev Splunk Docker image

  dev:up:
    deps: [__ensure-image]
    cmds:
      - task: __dev-compose
        vars: { COMPOSE_ARGS: 'up -d' }
      - task: __wait-healthy
        vars: { WAIT_CONTAINER: '{{.SPLUNK_CONTAINER}}' }
      - task: dev:ensure-links
    desc: Start dev Splunk, wait for health, then sync app symlinks

  dev:down:
    cmds:
      - task: __dev-compose
        vars: { COMPOSE_ARGS: 'down' }
    desc: Stop dev Splunk container

  dev:clean:
    cmds:
      - task: __dev-compose
        vars: { COMPOSE_ARGS: 'down -v' }
    desc: Stop dev Splunk, remove containers and volumes (full reset)

  dev:restart:
    cmds:
      - task: __dev-compose
        vars: { COMPOSE_ARGS: 'restart {{.SPLUNK_SERVICE}}' }
    desc: Restart dev Splunk container (entrypoint-wrapper skips Ansible)

  dev:restartd:
    deps: [__dev:ensure-running]
    cmds:
      - task: __dev-compose
        vars: { COMPOSE_ARGS: 'exec {{.SPLUNK_SERVICE}} bash -lc "{{.SPLUNK_BIN}} restart -auth admin:\$SPLUNK_PASSWORD"' }
    desc: Restart splunkd process inside running container (~10s)

  dev:refresh:
    deps: [__dev:ensure-running]
    cmds:
      - |
        echo "Reloading app configs..."
      - task: __dev-compose
        vars: { COMPOSE_ARGS: 'exec {{.SPLUNK_SERVICE}} bash -lc ''curl -sk -X POST https://localhost:8089/services/apps/local/_reload -u "admin:${SPLUNK_PASSWORD}" -o /dev/null -w "%{http_code}\n"''' }
      - |
        echo "Restarting Splunk Web (picks up static asset changes)..."
      - task: __dev-compose
        vars: { COMPOSE_ARGS: 'exec {{.SPLUNK_SERVICE}} bash -lc ''curl -sk -X POST https://localhost:8089/services/server/control/restart_webui -u "admin:${SPLUNK_PASSWORD}" -o /dev/null -w "%{http_code}\n"''' }
      - |
        echo "Done. Config and static assets reloaded (no restart needed)."
    desc: Reload app configs + static assets without restarting splunkd

  dev:reprovision:
    deps: [__dev:ensure-running]
    cmds:
      - |
        echo "Removing provisioning marker and restarting..."
      - task: __dev-compose
        vars: { COMPOSE_ARGS: 'exec --user root {{.SPLUNK_SERVICE}} bash -c "rm -f /opt/splunk/var/.provisioned"' }
      - task: dev:restart
      - |
        echo "Full Ansible provisioning will run. Follow with: task dev:logs"
    desc: Force full Ansible re-provisioning (removes marker + restarts)

  dev:ensure-links:
    deps: [__dev:ensure-running]
    cmds:
      - task: app:sync-links
    desc: Sync app symlinks in Splunk container (idempotent, run after dev:clean)

  dev:status:
    cmds:
      - task: __dev-compose
        vars: { COMPOSE_ARGS: 'ps {{.SPLUNK_SERVICE}}' }
    desc: Check dev Splunk container status

  dev:logs:
    cmds:
      - task: __dev-compose
        vars: { COMPOSE_ARGS: 'logs -f {{.SPLUNK_SERVICE}}' }
    desc: Follow dev Splunk container logs

  # ── Staging Splunk Lifecycle ───────────────────────────────────────

  stage:package:
    cmds:
      - |
        echo "Packaging all apps in {{.CONFIG_APPS_DIR}}/ ..."
        mkdir -p "{{.STAGE_DIR}}"
        for APP_DIR in {{.CONFIG_APPS_DIR}}/*/; do
          [ -d "$APP_DIR" ] || continue
          APP=$(basename "$APP_DIR")
          case "$APP" in .*) continue ;; esac
          TAR_PATH="{{.STAGE_DIR}}/${APP}.tgz"
          echo "  $APP → $TAR_PATH"
          tar -czf "$TAR_PATH" -C "{{.CONFIG_APPS_DIR}}" "$APP"
        done
        echo "All apps packaged to {{.STAGE_DIR}}/"
    desc: Package all apps from splunk/config/apps/ into splunk/stage/

  stage:up:
    deps: [__ensure-image]
    cmds:
      - task: __stage-compose
        vars: { COMPOSE_ARGS: 'up -d' }
      - task: __wait-healthy
        vars: { WAIT_CONTAINER: '{{.STAGING_CONTAINER}}' }
    desc: Start staging Splunk and wait for healthy

  stage:install:
    deps: [stage:package, stage:up]
    cmds:
      - |
        echo "Installing apps from {{.STAGE_DIR}}/ into staging..."
        INSTALLED=0; SKIPPED=0
        for TGZ in {{.STAGE_DIR}}/*.tgz {{.STAGE_DIR}}/*.tar.gz; do
          [ -f "$TGZ" ] || continue
          FILENAME=$(basename "$TGZ")
          echo "  Installing $FILENAME..."
          docker exec --user splunk {{.STAGING_CONTAINER}} bash -lc \
            "{{.SPLUNK_BIN}} install app /tmp/apps/${FILENAME} -update true -auth admin:\$SPLUNK_PASSWORD" \
            2>&1 && INSTALLED=$((INSTALLED + 1)) || SKIPPED=$((SKIPPED + 1))
        done
        echo "Install complete: $INSTALLED installed, $SKIPPED failed"
    desc: Install all tgz from splunk/stage/ into running staging (deps auto-package + start)

  stage:deploy:
    cmds:
      - task: stage:install
    desc: Package all apps, start staging, and install (convenience alias)

  stage:down:
    cmds:
      - task: __stage-compose
        vars: { COMPOSE_ARGS: 'down' }
    desc: Stop staging Splunk container

  stage:clean:
    cmds:
      - task: __stage-compose
        vars: { COMPOSE_ARGS: 'down -v' }
    desc: Stop staging Splunk, remove containers and volumes

  stage:logs:
    cmds:
      - task: __stage-compose
        vars: { COMPOSE_ARGS: 'logs -f' }
    desc: Follow staging Splunk container logs

  # ── App Management ───────────────────────────────────────────────────


  app:sync-links:
    deps: [__dev:ensure-running]
    cmds:
      - |
        CONTAINER="{{.SPLUNK_CONTAINER}}"
        echo "Syncing app symlinks in $CONTAINER ..."
        docker exec --user root "$CONTAINER" bash -c '
          DEV_APPS="/opt/splunk/dev-apps"
          ETC_APPS="/opt/splunk/etc/apps"
          CREATED=0; REPLACED=0; SKIPPED=0
          if [ -d "$DEV_APPS" ]; then
            for APP_PATH in "$DEV_APPS"/*/; do
              [ -d "$APP_PATH" ] || continue
              APP=$(basename "$APP_PATH")
              case "$APP" in .*) continue ;; esac
              LINK="$ETC_APPS/$APP"
              if [ -L "$LINK" ]; then
                SKIPPED=$((SKIPPED + 1))
              else
                [ -e "$LINK" ] && rm -rf "$LINK" && REPLACED=$((REPLACED + 1))
                ln -s "$DEV_APPS/$APP" "$LINK"
                CREATED=$((CREATED + 1))
              fi
            done
          fi
          CLEANED=0
          for LINK in "$ETC_APPS"/*; do
            [ -L "$LINK" ] || continue
            TARGET=$(readlink "$LINK")
            case "$TARGET" in "$DEV_APPS"/*)
              [ ! -d "$TARGET" ] && rm -f "$LINK" && CLEANED=$((CLEANED + 1))
              ;;
            esac
          done
          echo "Symlinks: $CREATED created ($REPLACED replaced), $SKIPPED existing, $CLEANED stale removed"

          # Grant devcontainer user (UID 1000) write access to bind-mounted dirs via ACL.
          # Required on Linux hosts where Splunk (UID 41812) owns the files.
          # On Mac/OrbStack this is a harmless no-op (VirtioFS handles permissions).
          for MNT in /opt/splunk/dev-apps /opt/splunk/react /opt/splunk/ucc-apps; do
            [ -d "$MNT" ] || continue
            setfacl -R -m u:1000:rwX "$MNT" 2>/dev/null || true
            setfacl -R -d -m u:1000:rwX "$MNT" 2>/dev/null || true
          done

          # Open Splunk var dirs so ansible user can run 'splunk cmd python3' without warnings
          setfacl -R -m u:ansible:rwX /opt/splunk/var/ 2>/dev/null || true
          setfacl -R -d -m u:ansible:rwX /opt/splunk/var/ 2>/dev/null || true
        '
    desc: Sync symlinks in Splunk etc/apps/ for each app in dev-apps/ (idempotent)

  app:create:
    deps: [__ensure-app-name]
    cmds:
      - |
        APP_DIR="{{.CONFIG_APPS_DIR}}/{{.APP_NAME}}"
        if [ -d "$APP_DIR" ]; then echo "App already exists: $APP_DIR (skipping)"; exit 0; fi
        APP_LABEL=$(echo "{{.APP_NAME}}" | tr '_-' '  ')
        echo "Creating app skeleton at $APP_DIR ..."
        mkdir -p "$APP_DIR/default" "$APP_DIR/metadata" "$APP_DIR/appserver/static" "$APP_DIR/bin"
        printf '%s\n' \
          "[install]" "state = enabled" "is_configured = 0" "" \
          "[ui]" "is_visible = 1" "label = ${APP_LABEL}" "" \
          "[launcher]" "author = developer" "version = 1.0.0" "description = ${APP_LABEL}" "" \
          "[package]" "id = {{.APP_NAME}}" \
          > "$APP_DIR/default/app.conf"
        printf '%s\n' \
          "[]" "access = read : [ * ], write : [ admin, power ]" "export = system" \
          > "$APP_DIR/metadata/default.meta"
        echo "App created: $APP_DIR"
      - task: dev:ensure-links
      - task: dev:refresh
        ignore_error: true
    desc: Scaffold a new Splunk app skeleton (idempotent — skips if exists)

  app:package:
    deps: [__ensure-app-name]
    cmds:
      - |
        SRC_DIR="{{.CONFIG_APPS_DIR}}/{{.APP_NAME}}"
        if [ ! -d "$SRC_DIR" ]; then echo "App not found: $SRC_DIR"; exit 1; fi
        mkdir -p "{{.STAGE_DIR}}"
        TAR_PATH="{{.STAGE_DIR}}/{{.APP_NAME}}.tgz"
        echo "Packaging $SRC_DIR → $TAR_PATH"
        tar -czf "$TAR_PATH" -C "{{.CONFIG_APPS_DIR}}" "{{.APP_NAME}}"
        echo "Created $TAR_PATH"
    desc: Package splunk/config/apps/<APP_NAME> into splunk/stage/<APP_NAME>.tgz

  # ── Dependency Management ────────────────────────────────────────────

  deps:install:
    deps: [__dev:ensure-running]
    cmds:
      - python3 splunk/scripts/deps-install.py --env-file "{{.ENV_FILE}}" --deps-file "{{.DEPS_FILE}}" --stage-dir "{{.STAGE_DIR}}" --compose-file "{{.COMPOSE_FILE}}" --service "{{.SPLUNK_SERVICE}}"
    desc: Install Splunkbase dependencies from splunk/config/deps.yml (idempotent)

  # ── React Development ─────────────────────────────────────────────────
  #
  # @splunk/create convention:
  #   react/packages/<app>/stage/  ← webpack outputs a COMPLETE Splunk app here
  #   yarn start                   ← webpack watch, stage/ updates live
  #   yarn build                   ← production build to stage/
  #
  # Dev loop: react:create → react:link → react:start (webpack watch)
  #           Splunk reads stage/ directly via symlink — no copying needed.
  # Staging:  react:package → stage:up (tgz auto-installed from splunk/stage/)

  # ── Internal: resolve REACT_APP_PATH ───────────────────────────────
  # Uses {{.APP_NAME}} (from dotenv or CLI) to find the React package dir.
  # Writes REACT_APP_NAME and REACT_APP_PATH to .task/react-env for
  # downstream tasks (REACT_APP_PATH is computed, needs temp file).
  __react:resolve:
    internal: true
    deps: [__ensure-app-name]
    cmds:
      - |
        REACT_PATH=""
        if [ -d "{{.REACT_PACKAGES_DIR}}/packages/{{.APP_NAME}}" ]; then
          REACT_PATH="{{.REACT_PACKAGES_DIR}}/packages/{{.APP_NAME}}"
        elif [ -d "{{.REACT_PACKAGES_DIR}}/{{.APP_NAME}}" ]; then
          REACT_PATH="{{.REACT_PACKAGES_DIR}}/{{.APP_NAME}}"
        else
          for d in "{{.REACT_PACKAGES_DIR}}/packages"/*/; do
            [ -d "${d}src/main/webapp/pages" ] && REACT_PATH="${d%/}" && break
          done
        fi
        if [ -z "${REACT_PATH}" ]; then
          echo "Cannot resolve React app — set APP_NAME in .env or run react:create"; exit 1
        fi
        mkdir -p .task
        printf 'REACT_APP_NAME=%s\nREACT_APP_PATH=%s\n' "{{.APP_NAME}}" "${REACT_PATH}" > .task/react-env

  # ── Internal: ensure stage/ exists (build only if missing) ──────────
  __react:ensure-build:
    internal: true
    deps: [__react:resolve]
    cmds:
      - |
        . .task/react-env
        if [ -d "${REACT_APP_PATH}/stage" ]; then exit 0; fi
        echo "stage/ not found — running initial build..."
        (cd "{{.REACT_PACKAGES_DIR}}" && yarn install --silent)
        (cd "${REACT_APP_PATH}" && yarn build)

  react:create:
    cmds:
      - |
        echo "Scaffolding React app with @splunk/create..."
        mkdir -p {{.REACT_PACKAGES_DIR}}
        if [ -n "{{.APP_NAME}}" ]; then
          cd {{.REACT_PACKAGES_DIR}} && node bin/splunk-create-noninteractive.mjs app "{{.APP_NAME}}"
        else
          cd {{.REACT_PACKAGES_DIR}} && npx @splunk/create
        fi
        echo ""
        echo "React app scaffolded."
      - |
        # Detect the app package: has src/main/webapp/pages/ (Splunk app structure)
        # Component libraries do NOT have this — they have a flat src/ with components
        REACT_PKG=""
        for d in "{{.REACT_PACKAGES_DIR}}/packages"/*/; do
          [ -d "${d}src/main/webapp/pages" ] || continue
          REACT_PKG=$(node -e "process.stdout.write(require('$(pwd)/${d}package.json').name.replace(/^@[^/]+\//,''))" 2>/dev/null || true)
          REACT_PATH="${d%/}"
          [ -n "$REACT_PKG" ] && break
        done
        if [ -z "$REACT_PKG" ]; then
          echo "Could not detect app package. Set APP_NAME manually in .env."
          exit 0
        fi
        echo "Detected app package: $REACT_PKG"
        # Sync APP_NAME in .env
        if [ -f "{{.ENV_FILE}}" ]; then
          if grep -q '^APP_NAME=' "{{.ENV_FILE}}"; then
            sed -i.bak "s|^APP_NAME=.*|APP_NAME=${REACT_PKG}|" "{{.ENV_FILE}}" && rm -f "{{.ENV_FILE}}.bak"
          else
            echo "APP_NAME=${REACT_PKG}" >> "{{.ENV_FILE}}"
          fi
          echo "Updated .env: APP_NAME=${REACT_PKG}"
        fi
        # Initial build so stage/ exists for react:link
        echo "Running initial build..."
        (cd "{{.REACT_PACKAGES_DIR}}" && yarn install)
        (cd "${REACT_PATH}" && yarn build)
        echo "Done. Next: task react:link && task react:start"
    desc: Scaffold React app via @splunk/create — non-interactive if APP_NAME set, else interactive

  react:add-page:
    cmds:
      - |
        if [ -n "{{.PAGE_NAME}}" ] && [ -n "{{.APP_NAME}}" ]; then
          echo "Adding page '{{.PAGE_NAME}}' to app '{{.APP_NAME}}' (non-interactive)..."
          cd {{.REACT_PACKAGES_DIR}} && node bin/splunk-create-noninteractive.mjs page "{{.PAGE_NAME}}" --app "{{.APP_NAME}}"
        else
          echo "Adding page/component via @splunk/create (interactive)..."
          cd {{.REACT_PACKAGES_DIR}} && npx @splunk/create
        fi
        echo "Installing new packages..."
        cd {{.REACT_PACKAGES_DIR}} && yarn install
        echo ""
        echo "Done. Run 'task react:start' to rebuild, or 'task react:package' for staging."
    desc: Add page to existing app — non-interactive if PAGE_NAME + APP_NAME set, else interactive

  react:add-component:
    cmds:
      - |
        if [ -n "{{.COMPONENT_NAME}}" ]; then
          echo "Adding component '{{.COMPONENT_NAME}}' (non-interactive)..."
          cd {{.REACT_PACKAGES_DIR}} && node bin/splunk-create-noninteractive.mjs component "{{.COMPONENT_NAME}}" --type "{{.COMPONENT_TYPE | default "basic"}}"
        else
          echo "Adding component via @splunk/create (interactive)..."
          cd {{.REACT_PACKAGES_DIR}} && npx @splunk/create
        fi
        echo "Installing new packages..."
        cd {{.REACT_PACKAGES_DIR}} && yarn install
        echo ""
        echo "Done."
    desc: Add component library — non-interactive if COMPONENT_NAME set, else interactive

  react:link:
    deps: [__react:ensure-build, __dev:ensure-running]
    cmds:
      - |
        . .task/react-env
        CONTAINER_STAGE="/opt/splunk/react/packages/${REACT_APP_NAME}/stage"
        echo "Linking ${CONTAINER_STAGE} → /opt/splunk/etc/apps/${REACT_APP_NAME} ..."
        docker exec --user root {{.SPLUNK_CONTAINER}} bash -c "
          LINK=/opt/splunk/etc/apps/${REACT_APP_NAME}
          [ -L \"\$LINK\" ] && rm -f \"\$LINK\"
          [ -e \"\$LINK\" ] && rm -rf \"\$LINK\"
          ln -s ${CONTAINER_STAGE} \"\$LINK\"
          echo \"Linked: \$LINK → ${CONTAINER_STAGE}\"
        "
      - task: dev:refresh
    desc: Symlink stage/ into dev Splunk (idempotent, auto-builds if stage/ missing)

  react:start:
    deps: [__react:ensure-build]
    cmds:
      - |
        . .task/react-env
        echo "Starting webpack watch in ${REACT_APP_PATH} ..."
        cd "${REACT_APP_PATH}" && yarn start
    desc: webpack watch — stage/ updates live, Splunk reads changes via react:link symlink

  react:build:
    deps: [__react:resolve]
    cmds:
      - |
        . .task/react-env
        echo "Building ${REACT_APP_NAME} for production..."
        (cd "{{.REACT_PACKAGES_DIR}}" && yarn install --silent)
        (cd "${REACT_APP_PATH}" && yarn build)
        [ -d "${REACT_APP_PATH}/stage" ] || { echo "Build failed — stage/ not found"; exit 1; }
        echo "Build complete → ${REACT_APP_PATH}/stage/"
    desc: Production webpack build (always rebuilds stage/)

  react:package:
    deps: [react:build]
    cmds:
      - |
        . .task/react-env
        STAGE_PATH="${REACT_APP_PATH}/stage"
        # Package stage/ as <APP_NAME>.tgz (macOS-compatible: temp symlink instead of --transform)
        mkdir -p "{{.STAGE_DIR}}"
        TGZ="{{.STAGE_DIR}}/${REACT_APP_NAME}.tgz"
        TMPDIR=$(mktemp -d)
        ln -s "$(cd "${STAGE_PATH}" && pwd)" "${TMPDIR}/${REACT_APP_NAME}"
        tar -chzf "${TGZ}" -C "${TMPDIR}" "${REACT_APP_NAME}"
        rm -rf "${TMPDIR}"
        echo "Packaged → ${TGZ}"
        echo "Deploy: task stage:up (auto-installs from splunk/stage/)"
    desc: Build + package stage/ as splunk/stage/<APP_NAME>.tgz for staging

  # ── UCC Add-on Development ────────────────────────────────────────────
  #
  # UCC (Universal Configuration Console) convention:
  #   ucc/<addon>/globalConfig.json  ← single source of truth for UI/config/inputs
  #   ucc/<addon>/package/           ← source: bin/, lib/, default/, app.manifest
  #   ucc/output/<addon>/            ← ucc-gen build output (generated, gitignored)
  #
  # Dev loop: ucc:init → ucc:build → ucc:link → ucc:dev (build+link+refresh)
  # Staging:  ucc:package → stage:deploy (tgz auto-installed from splunk/stage/)

  # ── Internal: resolve UCC addon path ────────────────────────────────
  __ucc:resolve:
    internal: true
    deps: [__ensure-app-name]
    cmds:
      - |
        UCC_PATH=""
        if [ -d "{{.UCC_SRC_DIR}}/{{.APP_NAME}}" ]; then
          UCC_PATH="{{.UCC_SRC_DIR}}/{{.APP_NAME}}"
        else
          # Auto-detect: find first dir with globalConfig.json
          for d in "{{.UCC_SRC_DIR}}"/*/; do
            [ -f "${d}globalConfig.json" ] && UCC_PATH="${d%/}" && break
          done
        fi
        if [ -z "${UCC_PATH}" ]; then
          echo "Cannot resolve UCC addon — set APP_NAME in .env or run ucc:init"; exit 1
        fi
        UCC_ADDON=$(basename "${UCC_PATH}")
        mkdir -p .task
        printf 'UCC_ADDON=%s\nUCC_PATH=%s\n' "${UCC_ADDON}" "${UCC_PATH}" > .task/ucc-env

  ucc:init:
    cmds:
      - |
        if [ -z "{{.APP_NAME}}" ]; then
          echo "ERROR: APP_NAME is required (pass APP_NAME=x or set in .env)"
          exit 1
        fi
        ADDON_DIR="{{.UCC_SRC_DIR}}/{{.APP_NAME}}"
        if [ -d "${ADDON_DIR}" ]; then
          echo "UCC addon already exists: ${ADDON_DIR} (skipping)"
          exit 0
        fi
        DISPLAY_NAME=$(echo "{{.APP_NAME}}" | tr '_-' '  ')
        INPUT_NAME=$(echo "{{.APP_NAME}}" | tr '-' '_' | sed 's/_input$//')_input
        REST_ROOT=$(echo "{{.APP_NAME}}" | tr '-' '_')

        echo "Scaffolding UCC add-on: {{.APP_NAME}} ..."
        mkdir -p "{{.UCC_SRC_DIR}}"
        cd "{{.UCC_SRC_DIR}}" && ucc-gen init \
          --addon-name "{{.APP_NAME}}" \
          --addon-display-name "${DISPLAY_NAME}" \
          --addon-input-name "${INPUT_NAME}" \
          --addon-rest-root "${REST_ROOT}" \
          --need-proxy \
          --overwrite

        echo ""
        echo "UCC add-on scaffolded at: ${ADDON_DIR}"
        echo "Key files:"
        echo "  ${ADDON_DIR}/globalConfig.json  — configuration (edit this)"
        echo "  ${ADDON_DIR}/package/            — source code"
        echo ""
        echo "Next: edit globalConfig.json, then run 'task ucc:dev'"
      - |
        # Sync APP_NAME in .env
        if [ -f "{{.ENV_FILE}}" ]; then
          if grep -q '^APP_NAME=' "{{.ENV_FILE}}"; then
            sed -i.bak "s|^APP_NAME=.*|APP_NAME={{.APP_NAME}}|" "{{.ENV_FILE}}" && rm -f "{{.ENV_FILE}}.bak"
          else
            echo "APP_NAME={{.APP_NAME}}" >> "{{.ENV_FILE}}"
          fi
        fi
    desc: Scaffold a new UCC add-on (creates globalConfig.json + package/)

  ucc:add-react:
    cmds:
      - |
        # Derive names from APP_NAME (e.g. my_addon → my-addon, my-addon-builder, builder)
        UCC_APP="{{.APP_NAME}}"
        REACT_APP=$(echo "${UCC_APP}" | tr '_' '-')
        COMPONENT_PKG="${REACT_APP//-app/}-builder"
        PAGE="{{.PAGE_NAME | default "builder"}}"
        REACT_DIR="$(pwd)/{{.REACT_PACKAGES_DIR}}"

        echo "Adding React UI to UCC app '${UCC_APP}'..."
        echo "  React app package:  ${REACT_APP}"
        echo "  Component library:  ${COMPONENT_PKG}"
        echo "  Page name:          ${PAGE}"
        echo ""

        # kebab-to-PascalCase helper
        to_pascal() { echo "$1" | sed 's/-\([a-z]\)/\U\1/g;s/^\([a-z]\)/\U\1/'; }

        # 1. Scaffold component library
        echo "── Scaffolding component library: ${COMPONENT_PKG} ──"
        (cd "${REACT_DIR}" && node bin/splunk-create-noninteractive.mjs component "$(to_pascal "${COMPONENT_PKG}")")
        echo ""

        # 2. Scaffold Splunk app wrapper
        echo "── Scaffolding app wrapper: ${REACT_APP} ──"
        (cd "${REACT_DIR}" && node bin/splunk-create-noninteractive.mjs app "$(to_pascal "${REACT_APP}")")
        echo ""

        # 3. Adapt for UCC overlay
        echo "── Adapting for UCC overlay ──"
        (cd "${REACT_DIR}" && node bin/adapt-for-ucc.mjs \
          --app-pkg "${REACT_APP}" \
          --ucc-app "${UCC_APP}" \
          --component-pkg "${COMPONENT_PKG}" \
          --page "${PAGE}")
        echo ""

        # 4. Install deps + build
        echo "── Installing dependencies ──"
        (cd "${REACT_DIR}" && yarn install)
        echo ""
        echo "── Building ──"
        (cd "${REACT_DIR}" && yarn workspace "@splunk/${COMPONENT_PKG}" build)
        (cd "${REACT_DIR}" && yarn workspace "@splunk/${REACT_APP}" build)

        echo ""
        echo "Done. React UI added to ${UCC_APP}."
        echo "  Component library: {{.REACT_PACKAGES_DIR}}/packages/${COMPONENT_PKG}/"
        echo "  App wrapper:       {{.REACT_PACKAGES_DIR}}/packages/${REACT_APP}/"
        echo "  Stage output:      {{.REACT_PACKAGES_DIR}}/packages/${REACT_APP}/stage/"
        echo ""
        echo "Next: task ucc:build-full (builds UCC + React + merges)"
    desc: Add React UI to a UCC add-on (scaffolds component + app + adapts for UCC overlay)

  ucc:build:
    deps: [__ucc:resolve]
    cmds:
      - |
        . .task/ucc-env
        echo "Building UCC add-on: ${UCC_ADDON} ..."
        mkdir -p "{{.UCC_OUTPUT_DIR}}"

        # Determine version from git tag or default
        VERSION=$(git describe --tags --abbrev=0 2>/dev/null | sed 's/^v//' || echo "1.0.0")

        ucc-gen build \
          --source "${UCC_PATH}/package" \
          --config "${UCC_PATH}/globalConfig.json" \
          --ta-version "${VERSION}" \
          -o "{{.UCC_OUTPUT_DIR}}" \
          --overwrite

        # Post-build cleanup
        APP="{{.UCC_OUTPUT_DIR}}/${UCC_ADDON}"
        find "${APP}" -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
        find "${APP}" -name ".*" -not -name ".gitkeep" -delete 2>/dev/null || true
        find "${APP}/lib" -type d -name tests -exec rm -rf {} + 2>/dev/null || true
        find "${APP}/lib" -type d -name test -exec rm -rf {} + 2>/dev/null || true
        rm -rf "${APP}/lib/bin" 2>/dev/null

        # Strip all .so files — pure Python only, portable across all platforms
        find "${APP}/lib" -name "*.so" -delete 2>/dev/null || true

        # Merge custom conf fragments from package/default.d/ into UCC output.
        # UCC generates restmap.conf, web.conf, etc. — custom entries go in
        # default.d/ to avoid overwriting UCC output via package/default/.
        FRAGMENTS="${UCC_PATH}/package/default.d"
        if [ -d "${FRAGMENTS}" ]; then
          for frag in "${FRAGMENTS}"/*.conf; do
            [ -f "${frag}" ] || continue
            target="${APP}/default/$(basename "${frag}")"
            echo "" >> "${target}"
            cat "${frag}" >> "${target}"
            echo "  Merged fragment: $(basename "${frag}")"
          done
        fi

        # Remove local/ and local.meta from build output (created at dev-time, fails AppInspect)
        rm -rf "${APP}/local" 2>/dev/null
        rm -f "${APP}/metadata/local.meta" 2>/dev/null

        echo "Build complete → {{.UCC_OUTPUT_DIR}}/${UCC_ADDON}/"
    desc: Build UCC add-on (generates REST handlers, UI, conf files)

  ucc:link:
    deps: [__ucc:resolve, __dev:ensure-running]
    cmds:
      - |
        . .task/ucc-env
        OUTPUT_APP="{{.UCC_OUTPUT_DIR}}/${UCC_ADDON}"
        if [ ! -d "${OUTPUT_APP}" ]; then
          echo "ERROR: Build output not found at ${OUTPUT_APP}. Run: task ucc:build"
          exit 1
        fi
        # UCC output is bind-mounted at /opt/splunk/ucc-apps/ in the Splunk container
        CONTAINER_PATH="/opt/splunk/ucc-apps/${UCC_ADDON}"
        echo "Linking ${CONTAINER_PATH} → /opt/splunk/etc/apps/${UCC_ADDON} ..."
        # Ensure local/ and metadata/ are writable by Splunk (inputs.conf writes)
        mkdir -p "${OUTPUT_APP}/local"
        docker exec --user root {{.SPLUNK_CONTAINER}} bash -c "
          LINK=/opt/splunk/etc/apps/${UCC_ADDON}
          [ -L \"\$LINK\" ] && rm -f \"\$LINK\"
          [ -e \"\$LINK\" ] && rm -rf \"\$LINK\"
          ln -s ${CONTAINER_PATH} \"\$LINK\"
          chown -R splunk:splunk ${CONTAINER_PATH}/local/ 2>/dev/null || true
          chown splunk:splunk ${CONTAINER_PATH}/metadata/ 2>/dev/null || true
          echo \"Linked: \$LINK → ${CONTAINER_PATH}\"
        "
    desc: Symlink UCC build output into dev Splunk

  ucc:merge-react:
    deps: [__ucc:resolve, __react:resolve]
    cmds:
      - |
        . .task/ucc-env
        . .task/react-env
        STAGE="${REACT_APP_PATH}/stage"
        OUTPUT="{{.UCC_OUTPUT_DIR}}/${UCC_ADDON}"

        if [ ! -d "${STAGE}" ]; then
          echo "No React stage/ found — skipping merge."
          exit 0
        fi

        echo "Merging React assets into UCC output..."

        # Copy page bundles (JS) — strip execute perms for AppInspect
        if [ -d "${STAGE}/appserver/static/pages" ]; then
          mkdir -p "${OUTPUT}/appserver/static/pages"
          cp "${STAGE}"/appserver/static/pages/*.js "${OUTPUT}/appserver/static/pages/"
          chmod 644 "${OUTPUT}"/appserver/static/pages/*.js 2>/dev/null
          echo "  Copied page bundles"
        fi

        # Copy Mako templates — strip execute perms for AppInspect
        if [ -d "${STAGE}/appserver/templates" ]; then
          cp "${STAGE}"/appserver/templates/*.html "${OUTPUT}/appserver/templates/"
          chmod 644 "${OUTPUT}"/appserver/templates/*.html 2>/dev/null
          echo "  Copied Mako templates"
        fi

        # Copy view XMLs (additive — don't overwrite UCC views)
        if [ -d "${STAGE}/default/data/ui/views" ]; then
          for xml in "${STAGE}"/default/data/ui/views/*.xml; do
            name=$(basename "${xml}")
            if [ ! -f "${OUTPUT}/default/data/ui/views/${name}" ]; then
              cp "${xml}" "${OUTPUT}/default/data/ui/views/"
              chmod 644 "${OUTPUT}/default/data/ui/views/${name}" 2>/dev/null
              echo "  Added view: ${name}"
            fi
          done
        fi

        # Merge nav entries: add React views right after <nav>
        NAV="${OUTPUT}/default/data/ui/nav/default.xml"
        if [ -f "${NAV}" ]; then
          # Remove any existing default="true"
          sed -i 's/ default="true"//g' "${NAV}"
          # Collect React views to add (reverse order since each inserts after <nav>)
          REACT_VIEWS=""
          for xml in "${STAGE}"/default/data/ui/views/*.xml; do
            view=$(basename "${xml}" .xml)
            if ! grep -q "name=\"${view}\"" "${NAV}"; then
              REACT_VIEWS="${view} ${REACT_VIEWS}"
            fi
          done
          # Insert each view after <nav> line
          for view in ${REACT_VIEWS}; do
            sed -i "/<nav>/a\\    <view name=\"${view}\"/>" "${NAV}"
            echo "  Added nav entry: ${view}"
          done
          # Make first React view the default
          FIRST_VIEW=$(ls "${STAGE}"/default/data/ui/views/*.xml 2>/dev/null | head -1 | xargs basename 2>/dev/null | sed 's/\.xml//')
          if [ -n "${FIRST_VIEW}" ] && grep -q "name=\"${FIRST_VIEW}\"" "${NAV}"; then
            sed -i "s|name=\"${FIRST_VIEW}\"|name=\"${FIRST_VIEW}\" default=\"true\"|" "${NAV}"
          fi
        fi

        echo "React merge complete."
    desc: Merge React page bundles and views into UCC build output

  ucc:dev:
    deps: [__ucc:resolve]
    cmds:
      - task: ucc:build
      - task: ucc:merge-react
        ignore_error: true
      - task: ucc:link
      - task: dev:refresh
        ignore_error: true
      - |
        . .task/ucc-env
        echo ""
        echo "UCC add-on ${UCC_ADDON} deployed to dev Splunk."
        echo "Open: http://localhost:8000/en-US/app/${UCC_ADDON}/inputs"
    desc: Build + link + refresh — full UCC dev iteration loop

  ucc:package:
    deps: [__ucc:resolve]
    cmds:
      - task: ucc:build
      - |
        . .task/ucc-env
        OUTPUT_APP="{{.UCC_OUTPUT_DIR}}/${UCC_ADDON}"
        mkdir -p "{{.STAGE_DIR}}"
        echo "Packaging UCC add-on: ${UCC_ADDON} ..."
        ucc-gen package --path "${OUTPUT_APP}" -o "{{.STAGE_DIR}}"
        echo ""
        ls -la "{{.STAGE_DIR}}"/${UCC_ADDON}*.tar.gz 2>/dev/null || ls -la "{{.STAGE_DIR}}"/${UCC_ADDON}*.tgz 2>/dev/null
        echo ""
        echo "Deploy: task stage:deploy"
    desc: Build + package UCC add-on to splunk/stage/ for staging

  ucc:appinspect:
    deps: [__ucc:resolve]
    cmds:
      - |
        . .task/ucc-env
        APP_DIR="{{.UCC_OUTPUT_DIR}}/${UCC_ADDON}"
        if [ ! -d "${APP_DIR}" ]; then
          echo "UCC output not found. Run: task ucc:build"
          exit 1
        fi
        echo "Running AppInspect on ${APP_DIR} ..."
        splunk-appinspect inspect "${APP_DIR}" --mode precert \
          --included-tags cloud 2>&1 | tee /tmp/appinspect-output.txt
        echo ""
        # Extract summary
        echo "=== Summary ==="
        grep -E "error:|failure:|warning:|success:|Total:" /tmp/appinspect-output.txt
        echo ""
        # Show failures if any
        FAILURES=$(grep -c "FAILURE:" /tmp/appinspect-output.txt || true)
        if [ "$FAILURES" -gt 0 ]; then
          echo "=== Failures ==="
          grep -B1 -A3 "FAILURE:" /tmp/appinspect-output.txt
          exit 1
        fi
        echo "All checks passed."
    desc: Run Splunk AppInspect on UCC build output (precert mode)

  # ── Python Tooling ───────────────────────────────────────────────────

  python:lint:
    cmds:
      - ruff check {{.CONFIG_APPS_DIR}} || true
    desc: Lint Python code in splunk/config/apps/ with ruff

  python:format:
    cmds:
      - ruff format {{.CONFIG_APPS_DIR}} || true
    desc: Format Python code in splunk/config/apps/ with ruff

  python:test:
    cmds:
      - pytest {{.CONFIG_APPS_DIR}} || echo "No tests found or pytest not installed"
    desc: Run Python tests with pytest

  # ── Testing ─────────────────────────────────────────────────────────

  test:lifecycle:
    cmds:
      - |
        echo "Running lifecycle tests (guards, boot, app, deps, react, staging, skip-provision)..."
        bash tests/e2e/run-lifecycle.sh
    desc: Splunk lifecycle tests — 8 suites (works on any host with Docker + task)

  test:devcontainer:
    cmds:
      - |
        if command -v devcontainer &>/dev/null; then
          DC_CLI="devcontainer"
        else
          echo "devcontainer CLI not found, using npx..."
          DC_CLI="npx --yes @devcontainers/cli"
        fi
        echo "Running devcontainer tests (static checks + lifecycle)..."
        bash tests/e2e/devcontainer-test.sh
    desc: Build devcontainer, run static checks + lifecycle tests inside it

  test:all:
    cmds:
      - task: python:lint
      - task: test:devcontainer
    desc: All tests (lint + devcontainer)

  # ── Utility ──────────────────────────────────────────────────────────

  env:setup:
    cmds:
      - |
        if [ ! -f "{{.ENV_FILE}}" ]; then
          if [ -f "splunk.env.example" ]; then
            cp splunk.env.example "{{.ENV_FILE}}"
            echo ".env created from splunk.env.example"
          else
            echo "No splunk.env.example found"
          fi
        else
          echo ".env already exists"
        fi
    desc: Create .env from splunk.env.example (idempotent — skips if exists)