Previously install.sh short-circuited with "Image ... already present -
skipping load" whenever a tag with the same version already existed in
Docker. That optimization was actively harmful: if an earlier deploy
attempt had loaded a wrong-arch (e.g. arm64) image at the same tag, we'd
never load the corrected tarball in the current ZIP and the arch check
would keep failing against the stale image forever.
docker load reassigns the tag atomically to whatever is in the tarball and
is a fast no-op when the layers are already present, so unconditional load
is both safe and self-healing.
install.sh now also prints the loaded image id + arch and, on mismatch,
tells the operator to `git pull` on the build host before re-running
package.sh so they pick up the buildx/binfmt fixes.
Co-authored-by: Cursor <cursoragent@cursor.com>
The default buildx builder (docker driver) is bound to the daemon's native
platform, so on an Apple Silicon Mac `--platform linux/amd64 --load` was
silently producing an arm64 image. The bundle then failed on the linux/amd64
target host with the "exec format error" that install.sh's arch sanity
check now surfaces as "Image architecture (arm64) does not match this host
(amd64)".
package.sh now:
- Creates a dedicated `sha-remote-agent-builder` (docker-container driver)
on first run so cross-arch builds actually work.
- Best-effort installs tonistiigi/binfmt QEMU handlers when the target
platform differs from the host.
- Uses `--output type=docker,dest=...` instead of `--load` + `docker save`,
bypassing the local daemon's cross-arch storage limits entirely.
- Verifies the produced image's Architecture against --platform after the
build and aborts if they disagree, so a broken ZIP can never leave the
build host.
- Only re-tags :latest when the built platform matches the host, to avoid
leaving a broken cross-arch :latest in the local daemon.
README documents the trap and the mitigations.
Co-authored-by: Cursor <cursoragent@cursor.com>
Rebrand NetAnalyzer -> StoreHealthAnalyzer and consolidate the store
reporting surface into a single `st [number]` command with focused
sub-modes.
Commands
- st [number] - general info (SIW + brands + Meraki net link)
- st [number] network - switches, APs, store server
- st [number] pos - registers, payment terminals, customer display
- st [number] ios - MDM-tracked iOS hardware
- st [number] phone - wired 78xx + DECT basestations/handsets with
registration state, extensions and main DID
- st [number] av - Atlas AMPs + MDM-tracked Apple TVs, video
walls, music players, LED displays
- Removed `analyze` in favor of the unified `st` surface
Integrations
- integrations/webex: Service App OAuth with rotating refresh tokens,
seed + cleanup scripts, tokens/ storage (git-ignored)
- integrations/atlas: Xyte client + cached device discovery keyed on
zero-padded 6-digit store numbers, cold-cache failure -> unavailable
banner instead of a misleading empty result
- services/webexPhone, services/webexService, services/avService: shape
raw upstream data into the report layer's contract
- utils/merakiMatcher: FQDN hostname extraction so payment terminals
match Meraki descriptions; case-insensitive lookup
- utils/chunkReport: split long markdown replies at 7000-char boundaries
Reliability / ops
- server.js: awaited framework.stop() + 8s hard-kill timer so nodemon /
Docker restarts don't leak WDM device registrations ("excessive device
registrations")
- nodemon.json: SIGINT so the graceful path always runs
- scripts/cleanupWebexDevices.js: one-shot WDM cleanup utility
- Group-space routing: hears() regexes tolerate the leading @BotName
prefix Webex prepends to mentions
- Replaced HTML-unsafe <number> placeholders with [number] in all help
strings
Remote agent containerization
- docker/remote-agent/: multi-stage node:22-alpine image, non-root user,
tini for signal handling, minimal deps (ws/axios/dotenv)
- docker/remote-agent/package.sh: docker buildx build defaulting to
linux/amd64 (with override), saves image + assembles deploy/ + writes
SHA256 + zips for offline transfer
- docker/remote-agent/deploy/: runtime docker-compose.yml, install.sh
with platform sanity check, remote-host README
- .dockerignore + .gitignore updates for build artifacts and dist bundles
- npm run agent:package convenience script
Cleanup
- Dropped storeHealth.js / HealthReport.js and their tests/mocks in favor
of the shared storeDetail pipeline
- Store model handles null SIW records gracefully; toSummary always
ends with a newline so the Meraki link sits on its own line
Tests
- 144 tests across 14 suites passing; new coverage for atlasClient,
atlasDevices, avService, avCategory classification, webexPhone,
webexServiceAppAuth, storeDetail integration, siw, chunkReport and
the updated meraki matcher
Co-authored-by: Cursor <cursoragent@cursor.com>
- Initialize git repository
- Add comprehensive .gitignore (protects .env and secrets)
- Fix package.json (correct main entry, add metadata)
- Expand .env.example with all required variables and comments
- Add README.md with architecture, setup, and commands
- Clean up empty scaffolding directories (logs removed, agents/models marked)
- Backup previous .env file locally
This establishes a safe foundation before further development.
