tooling: add bin/update.sh wrapper for end-user updates

[commitconfirm]

Parent

Part of #3 (umbrella: end-user update path for v1.0).

Summary

Wrap the canonical update flow (documented in UPGRADE.md per
sub-issue A) into a single command: ./bin/update.sh. Target
audience is network engineers who can follow a process but don't
necessarily live in Docker daily — the wrapper turns a multi-step
sequence into one action with built-in verification.

Required behavior

• Pre-flight: confirm working tree clean (refuse to run with
  uncommitted changes unless --force is passed); confirm Docker
  daemon reachable; confirm docker compose available.
• Fetch: git fetch --tags.
• Decide what to pull: default behavior is git pull --ff-only
  against current branch. Optional --tag vX.Y.Z flag does
  git checkout vX.Y.Z instead. Refuse to pull if the branch
  isn't fast-forwardable.
• Detect what changed: diff the pull range and identify which
  service directories (controller/, etc.) were touched. Only
  rebuild affected services.
• Build: docker compose build <service-list>.
• Recreate: docker compose up -d <service-list>.
• Verify: poll healthchecks for affected services with a
  reasonable timeout; tail recent logs for common failure patterns
  (ImportError, Traceback, unhealthy).
• Report: print a clear success/failure summary at the end —
  what was updated, what's running, what to check if something
  looks off.

Required flags

• --dry-run: print what would happen without executing
• --tag vX.Y.Z: pin to a specific tag instead of branch head
• --force: bypass clean-working-tree check (with a warning)
• --all: rebuild all services instead of selective (escape hatch)
• --help: usage

Style

• Bash, set -euo pipefail.
• Self-contained — no external script dependencies beyond git,
  docker, docker compose, and standard POSIX tools.
• Clear output: each phase prints a heading; errors are loud;
  success is concise.
• Exit codes: 0 success, 1 user error (bad flag, dirty tree), 2
  update failed (build/recreate/healthcheck), 3 environment problem
  (no Docker, no git).

Acceptance criteria

• bin/update.sh exists, executable, and follows the behavior above
• UPGRADE.md references it as the recommended update method
• README's update section points to it
• Tested against a real install (the production host that hit
  issue Block C migration miss: discovery.py:_snmp_get still uses pysnmp 6.x API #1 is the natural candidate) — confirm dry-run output is
  accurate, selective rebuild correctly identifies changed services,
  verification correctly catches a deliberately-broken update
• No hardcoded paths, hostnames, IPs, or internal identifiers

Future enhancements (out of scope for v1.0)

• Self-update of the script itself
• Backup/snapshot integration (e.g., trigger a Proxmox snapshot via
  API before updating)
• Notification hooks (Slack, email) on update success/failure