feat(update): port CLI self-updater command to refactor architecture

[jariy17]

What

Ports the agentcore update command from the old CLI (main) into the refactored Handler/Router (Bun) architecture. update checks the npm registry for a newer @aws/agentcore and runs npm install -g; update --check reports availability without installing.

The refactor branch had resource-level update subcommands (gateway, harness, eval…) but no top-level self-updater — this adds it.

Changes

• src/handlers/update/action.ts (new) — fetchLatestVersion, compareVersions, installArgv, handleUpdate. The install runs through an injectable ProcessRunner (defaults to the shared runProcess from src/io/exec.ts), so the install path is testable without spawning a real npm.
• src/handlers/update/index.tsx (new) — createUpdateHandler; always renders the UpdateResult as JSON (matching the resource-command convention); npm progress streams to io.stderr so stdout stays a clean, pipeable JSON result; SilentCLIError for a non-zero exit on failed install.
• src/handlers/index.tsx — mounts the handler at the root (2 lines).
• src/handlers/update/update.test.ts (new) — compareVersions table, fetchLatestVersion fetch spy (200/404), and handleUpdate branches (up-to-date / newer-local / update-available / updated / update-failed) via an injected fake runner.

CLI surface

agentcore update           # check and install
agentcore update --check   # report availability only

Verification

• bun test src/handlers/update/ → 21 pass / 0 fail
• bunx tsc --noEmit → clean
• Live: update --help, update --check, update --check --json all correct

Notes

Faithful port of the old command's behavior (bare update installs; --check only checks). A separate adversarial bug bash surfaced pre-existing gaps carried over from the old CLI (dist-tag check/install channel mismatch, no CI/TTY install guard, unvalidated registry JSON) — not addressed here to keep this a clean port; happy to follow up.

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[codecov-commenter]

Codecov Report

❌ Patch coverage is 89.24731% with 10 lines in your changes missing coverage. Please review.
✅ Project coverage is 97.14%. Comparing base (f431dce) to head (3003400).
⚠️ Report is 21 commits behind head on refactor.

Files with missing lines	Patch %	Lines
src/handlers/update/index.tsx	57.14%	9 Missing ⚠️
src/handlers/update/action.ts	98.57%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##           refactor    #2151      +/-   ##
============================================
- Coverage     97.16%   97.14%   -0.03%     
============================================
  Files           495      497       +2     
  Lines         32676    32769      +93     
============================================
+ Hits          31751    31834      +83     
- Misses          925      935      +10     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[agentcore-devx-automation]

AgentCore Harness Review

Verdict: Looks good

Clean port of agentcore update into the refactored Handler/Router architecture. Nicely scoped:

• Business logic (fetchLatestVersion, compareVersions, handleUpdate) is separated from the handler shell.
• ProcessRunner is injected so the install path is covered without spawning real npm — mocking is at the true I/O boundary (matches the repo's guidance).
• fetch is spied via spyOn(globalThis, "fetch") and restored in afterEach — appropriately hermetic.
• renderJson is called before the SilentCLIError throw, so the JSON result reaches stdout even on a failed install, and the non-zero exit still surfaces to scripts.
• Telemetry is auto-instrumented at the router (cli.command_run with command_path), so no per-handler wiring is needed.

Known follow-ups already called out in the PR description (which I agree are out of scope for a "clean port"):

• installArgv() uses distTag() (@preview vs @latest), but fetchLatestVersion() always queries the /latest endpoint. For a preview build the check and the install target disagree — the check compares against stable, then installs from preview.
• No guard against running npm install -g in non-interactive/CI contexts, and the registry JSON isn't schema-validated.

Non-blocking observations for a future pass:

• PACKAGE_NAME = "@aws/agentcore" is hardcoded while the current package.json name on refactor is agentcore. Fine if this reflects the intended published name, but worth confirming before the branch actually ships.
• Test file is update.test.ts while the rest of src/handlers/ uses co-located index.test.ts. Minor.
• In the "newer-local" test (handleUpdate(false) with no injected runner), the branch returns before invoking the runner, so it's safe today, but passing a mock runner would make the test robust to future refactors of handleUpdate.

Nothing here needs to block merge.

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[AlexanderRichey]

This should be an AgentCoreCLIError. I think we should create a NetworkingError to cover this and other cases.

[AlexanderRichey]

This is looking a little gnarly! Can we not use semver?

[AlexanderRichey]

Why should this error be silent?

[AlexanderRichey]

I'd probably just put all of the functionality here. I don't see an upshot of pulling this out. I think code could still be tested easily enough if it were inlined here.