spark-store/docs/superpowers/plans/2026-04-15-update-notifier-apm-aggregation.md

Update Notifier APM Aggregation Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Extend tool/update-upgrade/ss-update-notifier.sh so one notifier aggregates effective Spark and APM updates, honoring hold status and shared ignored entries while skipping the Spark branch when aptss is unavailable.

Architecture: Keep the current notifier script as the single entrypoint and add a second APM counting branch beside the existing Spark branch. Reuse the existing ignored-entry loading logic, count Spark and APM updates independently after source-specific filtering, then combine the remaining counts into one notification.

Tech Stack: Bash, aptss, apm, amber-pm-debug, dpkg-query

---

File Structure

• Modify: tool/update-upgrade/ss-update-notifier.sh Responsibility: add APM update parsing and counting, guard Spark execution behind aptss availability, reuse ignored-entry filtering for both branches, and keep one aggregated notification path.

Task 1: Add Source-Specific Counting Helpers

Files:

• Modify: tool/update-upgrade/ss-update-notifier.sh

• Step 1: Write the failing shell behavior expectation as comments in the plan

# Expected behavior after implementation:
# 1. If aptss is missing, the script does not call aptss update/ssupdate.
# 2. If apm reports upgradable apps, ignored pkg|newVersion entries suppress them.
# 3. Spark and APM effective counts are added into one final count.

• Step 2: Run syntax check before changes

Run: bash -n tool/update-upgrade/ss-update-notifier.sh Expected: exit 0

• Step 3: Add minimal helper functions for APM parsing and per-source counting

function has-command() {
    command -v "$1" >/dev/null 2>&1
}

function get_apm_upgradable_list() {
    local output
    output=$(env LANGUAGE=en_US apm list --upgradable 2>/dev/null | awk 'NR>1')
    local ifs_old="$IFS"
    IFS=$'\n'
    for line in $output; do
        local pkg_name
        local pkg_new_ver
        local pkg_cur_ver
        pkg_name=$(echo "$line" | awk -F '/' '{print $1}')
        pkg_new_ver=$(echo "$line" | awk '{print $2}')
        pkg_cur_ver=$(printf '%s\n' "$line" | sed -n 's/.*\[\(upgradable from\|from\):[[:space:]]*\([^]]*\)\].*/\2/p')
        if [ -n "$pkg_name" ] && [ -n "$pkg_new_ver" ] && [ -n "$pkg_cur_ver" ]; then
            echo "$pkg_name $pkg_new_ver $pkg_cur_ver"
        fi
    done
    IFS="$ifs_old"
}

• Step 4: Re-run syntax check after helper changes

Run: bash -n tool/update-upgrade/ss-update-notifier.sh Expected: exit 0

Task 2: Aggregate Spark And APM Effective Counts

Files:

• Modify: tool/update-upgrade/ss-update-notifier.sh

• Step 1: Guard Spark refresh and counting behind aptss availability

spark_update_count=0
if has-command aptss; then
    # existing aptss update / aptss ssupdate logic
    # existing spark upgradable counting logic
fi

• Step 2: Add APM refresh and counting branch with hold + ignored filtering

apm_update_count=0
if has-command apm; then
    updatetext=$(LANGUAGE=en_US apm update 2>&1)
    # retry loop matching current script style
    apm clean
    PKG_LIST="$(get_apm_upgradable_list)"
    apm_update_count=$(printf '%s\n' "$PKG_LIST" | awk 'NF { count++ } END { print count + 0 }')
    # for each package:
    # - skip if new <= current
    # - skip if amber-pm-debug dpkg-query says hold
    # - skip if ignored_apps["$PKG_NAME|$PKG_NEW_VER"] exists
    # - otherwise increment apm_update_count
fi

• Step 3: Replace single-source final count with aggregated count

update_app_number=$((spark_update_count + apm_update_count))
if [ "$update_app_number" -le 0 ]; then
    exit 0
fi

• Step 4: Keep one final notification path

notify-send -a spark-store \
  "${TRANSHELL_CONTENT_SPARK_STORE_UPGRADE_NOTIFY}" \
  "${TRANSHELL_CONTENT_THERE_ARE_APPS_TO_UPGRADE}" || true

• Step 5: Re-run syntax check after aggregation changes

Run: bash -n tool/update-upgrade/ss-update-notifier.sh Expected: exit 0

Task 3: Verification And Commit

Files:

• Modify: tool/update-upgrade/ss-update-notifier.sh

• Step 1: Run notifier syntax verification

Run: bash -n tool/update-upgrade/ss-update-notifier.sh Expected: exit 0

• Step 2: Run repository lint

Run: npm run lint Expected: exit 0

• Step 3: Run repository build

Run: npm run build:vite Expected: exit 0

• Step 4: Review final diff

Run: git diff -- tool/update-upgrade/ss-update-notifier.sh docs/superpowers/specs/2026-04-15-update-notifier-apm-aggregation-design.md docs/superpowers/plans/2026-04-15-update-notifier-apm-aggregation.md Expected: only notifier aggregation and spec/plan changes appear

• Step 5: Commit

git add tool/update-upgrade/ss-update-notifier.sh docs/superpowers/specs/2026-04-15-update-notifier-apm-aggregation-design.md docs/superpowers/plans/2026-04-15-update-notifier-apm-aggregation.md
git commit -m "fix(update): 聚合 Spark 和 APM 升级通知"