docs(cli): list kiro in update target help

[WilliamK112]

Summary

• add kiro to the apm update --target help example list
• keep the command docstring aligned with the visible help text
• add a focused regression test for the help output

Context

Follow-up for #1817, item 3 in the CLI Consistency Report. kiro is supported by the target parser and documented in the CLI reference, but the apm update --target help examples still omitted it.

Testing

• .venv-codex/bin/python -m pytest tests/unit/test_update_command.py -q
• .venv-codex/bin/ruff check src/apm_cli/commands/update.py tests/unit/test_update_command.py
• .venv-codex/bin/apm update --help | rg -n 'Agent target|kiro|--target|claude,cursor'

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Updates apm update --help text to include the newly supported kiro target and adds a regression test to ensure the help output stays aligned with supported targets.

Changes:

• Add a unit test asserting apm update --help includes kiro and shows a --target example.
• Update update command documentation/help strings to list kiro among target examples.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
tests/unit/test_update_command.py	Adds a regression test to lock in --help output mentioning kiro and a --target usage example.
src/apm_cli/commands/update.py	Updates user-facing help text/documentation to include kiro in the target examples.

[WilliamK112]

Addressed in 8b06e49: the test now collects the --target help block and asserts --target, gemini, and kiro independently instead of matching a specific example/order. Validated with targeted pytest, ruff check, ruff format --check, and git diff --check.

[github-actions]

APM Review Panel: ship_with_followups

Correct fix for the sole update command gap; a CHANGELOG omission and --target ordering drift are the only loose ends worth an in-PR amendment before merge.

cc @WilliamK112 -- a fresh advisory pass is ready for your review.

The change is correct and unambiguous. kiro is fully registered in the codebase, all peer commands (install, compile, deps) already list it in --target examples, and the update command was the sole laggard. The diff is minimal -- two string literals plus one regression-pinning test -- and no panelist raised a blocking finding. The fix should land.

Two recommended findings deserve author attention before merge. doc-writer's call for a CHANGELOG entry is the stronger of the two: project convention explicitly requires a ### Fixed bullet for user-visible behavior changes, and kiro's original v0.20.0 introduction set that precedent correctly. A one-line addition under [Unreleased] closes this cleanly. devx-ux-expert's finding on --target ordering divergence is also real: after this PR, update lists kiro after gemini while the reference page places it between windsurf and codex, and install uses a different order still. Divergent ordering between sibling commands compounds with every new target addition and actively erodes first-run confidence in which list is authoritative.

The DRY gap (five command files maintaining independent --target example strings) and the test simplification nits are genuine but follow-up material. The shared constant refactor belongs in a dedicated PR where all five commands can be updated and validated together. The multi-line test collector nit is worth simplifying in a follow-up, but the existing test correctly pins the regression that motivated this contribution and passes on the current commit.

Dissent. devx-ux-expert classified the --target ordering divergence as recommended while cli-logging-expert and doc-writer treated the same observation as nit. The panel weights it as recommended: divergent ordering between sibling commands is a user-facing consistency defect that degrades first-run confidence -- it is not merely aesthetic. The maintainer should treat it as worth addressing in-PR rather than as follow-up noise.

Aligned with: Pragmatic as npm -- help text is the first touchpoint for users running apm update --help; consistent, canonically ordered target lists reduce cognitive load and match the mental model set by install, compile, and deps. OSS community-driven -- external contributor WilliamK112 identified a real inconsistency and followed the pattern established by peer commands; the two in-PR amendments (CHANGELOG, ordering) are mechanical and easy to address, and a fast merge cycle here reinforces that APM is a project where community fixes land quickly.

Growth signal. New target additions are a recurring launch beat opportunity. Consistent help-string examples are prerequisite copy for quickstarts and social posts -- a --target list that disagrees with itself across commands undercuts any "kiro is supported" announcement. The CONTRIBUTING.md checklist gap means the next target addition will likely repeat this cycle. A one-line checklist item doubles as a content-readiness gate for launch comms and takes five minutes to add.

Panel summary

Persona	B	R	N	Takeaway
Python Architect	0	0	2	Correct, minimal, no-risk fix closing the consistency gap with install, compile, and deps; two nits on DRY gap and test complexity.
CLI Logging Expert	0	0	2	No required findings; two nits on test naming and example ordering consistency.
DevX UX Expert	0	1	1	update --target example list is out of sync with install --target in ordering and content; minor test complexity nit.
Supply Chain Security Expert	0	0	0	No supply-chain security surface touched; help text change only, no new dependencies or auth paths.
OSS Growth Hacker	0	0	1	No blocking growth issues; one process nit around help-string consistency for new target additions.
Doc Writer	0	1	1	Two doc-consistency issues: --target example order diverges from the reference page, and the fix lacks a CHANGELOG entry.
Test Coverage Expert	0	0	1	New test correctly covers the kiro addition; one nit on brittle multi-line parser and trivially true assertion.

B = blocking-severity findings, R = recommended, N = nits.
Counts are signal strength, not gates. The maintainer ships.

Top 5 follow-ups

1. [Doc Writer] Add a CHANGELOG [Unreleased] ### Fixed entry for this help-text fix. -- Project convention requires a ### Fixed bullet for every user-visible behavior change; the omission breaks the audit trail and is a one-line fix: - \apm update --target` help text now lists `kiro` as a valid example target, matching `apm install`. (docs(cli): list kiro in update target help #1821)`
2. [DevX UX Expert] Reorder the --target example list in update.py to match the CLI reference page order: claude, copilot, cursor, windsurf, kiro, codex, opencode, gemini. -- After this PR, update and install list targets in divergent orders, and the in-binary help disagrees with docs/src/content/docs/reference/cli/update.md line 46; divergent ordering compounds with each new target addition and erodes first-run confidence.
3. [OSS Growth Hacker] Add an "adding a new target" checklist item to CONTRIBUTING.md requiring help-string example consistency and canonical ordering across all command files. -- At least the second PR where a new target shipped without aligned example strings across all commands; a CONTRIBUTING.md gate prevents the cycle from repeating.
4. [Python Architect] Extract a shared _TARGET_HELP_EXAMPLES constant in targets.py so all five command files reference a single source of truth for --target example strings. -- Five independently maintained strings guarantee drift on every new target addition; a dedicated refactor PR can update all five commands together.
5. [Test Coverage Expert] Simplify the new test to self.assertIn("kiro", result.output) and drop the multi-line --target section collector. -- The collector is sensitive to Click's terminal-width formatting and includes a trivially true assertion (assertIn("--target", target_help)); a direct assertIn on result.output is equally precise and more robust.

Architecture

classDiagram
    direction LR
    class update_module {
        <<Module>>
        +module_docstring str
        +update() Click.Command
    }
    class update {
        <<Command>>
        +packages tuple
        +target list
        +assume_yes bool
        +dry_run bool
        +verbose bool
    }
    class _UpdateRunState {
        <<Dataclass>>
        +plan UpdatePlan
        +proceeded bool
        +revision_pins_applied bool
    }
    class TargetParamType {
        <<Converter>>
        +convert(value, param, ctx) list
    }
    class TargetProfile {
        <<ValueObject>>
        +name str
        +root_dir str
        +primitives dict
    }
    class targets_module {
        <<Module>>
        +TARGET_PROFILES dict
    }
    class TestUpdateCommand {
        <<TestCase>>
        +runner CliRunner
        +test_update_kiro_in_help()
    }
    update_module *-- update : defines
    update *-- _UpdateRunState : creates
    update ..> TargetParamType : target option
    TargetParamType ..> targets_module : validates against
    targets_module *-- TargetProfile : kiro entry
    TestUpdateCommand ..> update_module : invokes via CliRunner
    class update_module:::touched
    class TestUpdateCommand:::touched
    classDef touched fill:#fff3b0,stroke:#d47600

Loading

flowchart TD
    A["CLI: apm update --help"] --> B["Click router\napm_cli/cli.py"]
    B --> C["update() command\ncommands/update.py"]
    C --> D["Click emits help text\nfrom --target option\nhelp= string literal"]
    D --> E["Help string now includes\n'...gemini, kiro.'\nupdate.py lines 42 and 254"]
    E --> F["CliRunner.invoke captures stdout\ntest_update_command.py"]
    F --> G["Multi-line parser collects\n-t, --target block"]
    G --> H{"assertIn checks"}
    H --> |"assertIn 'gemini'"| I["PASS"]
    H --> |"assertIn 'kiro'"| I
    H --> |"either missing"| J["FAIL / regression"]
    style E fill:#fff3b0,stroke:#d47600
    style G fill:#fff3b0,stroke:#d47600

Loading

Recommendation

The fix is correct and the contribution is welcome. Items 1 and 2 (CHANGELOG entry and target ordering) are small enough that the maintainer may choose to ask the author for an in-PR amendment or fold them in directly; either path is fine. Items 3 through 5 belong in follow-up issues rather than holding up this PR. Once the CHANGELOG and ordering are addressed -- however the maintainer prefers to handle them -- this change is ready to land.

---

Full per-persona findings

Python Architect

• [nit] Design patterns / pre-existing DRY gap in --target example strings at src/apm_cli/commands/update.py:254
  Five command files (install.py, update.py, compile/cli.py, deps/cli.py, _helpers.py) maintain independently-edited --target example strings. A shared _TARGET_HELP_EXAMPLES constant extracted to targets.py would make future target additions a single-line change instead of a five-file grep.
  Suggested: Extract shared target example string to targets.py or a shared constants module; reference it from all command help= arguments.

• [nit] Test name is verbose; line-scanning loop is defensible but text-layout-sensitive at tests/unit/test_update_command.py:259
test_dependency_update_help_lists_kiro_target_example is wordy. The line-scan loop is sensitive to Click's max_content_width and terminal width. self.assertIn("kiro", result.output) is equally precise and far easier to read.
  Suggested: Rename to test_update_target_help_includes_kiro. Optionally simplify to self.assertIn("kiro", result.output).

CLI Logging Expert

• [nit] Test method name implies apm deps update scope, not apm update at tests/unit/test_update_command.py:259
  The prefix test_dependency_update_* mirrors the deps update sub-command naming convention used elsewhere; a reader scanning for apm update help tests will overlook this.
  Suggested: Rename to test_update_help_lists_kiro_as_target_example.

• [nit] --target example list order in help text diverges from CANONICAL_TARGETS_ORDERED at src/apm_cli/commands/update.py:254
  When the canonical order and the help-text example order drift, future additions will replicate the inconsistency. Keeping both in sync is the low-effort way to prevent drift from compounding.
  Suggested: Reorder the example to match CANONICAL_TARGETS_ORDERED in target_detection.py, inserting kiro at the same relative position.

DevX UX Expert

• [recommended] update --target example list diverges from install --target in ordering and content at src/apm_cli/commands/update.py:254
  After this PR, update examples enumerate claude, copilot, cursor, windsurf, codex, opencode, gemini, kiro while install lists targets in a different order and includes antigravity and agent-skills. Sibling commands with divergent target lists force users to wonder which list is authoritative -- exactly the doubt that kills first-run confidence.
  Suggested: Extract a shared SUPPORTED_TARGETS constant and reference it in both install and update help text so the lists stay in sync automatically.

• [nit] Multi-line output collector in test adds indirection without stronger coverage at tests/unit/test_update_command.py:262
self.assertIn("kiro", result.output) is equally precise and immediately readable; the multi-line collector pattern adds cognitive overhead without catching any additional failure modes.

Supply Chain Security Expert

No findings.

OSS Growth Hacker

• [nit] No checklist gate for consistent help-string examples when adding a new target at CONTRIBUTING.md
  This is at least the second PR where a new target shipped without short-example strings aligned across all commands. Help strings are a micro-conversion surface -- a user who sees the tool in one command but not another reasonably doubts whether support exists.
  Suggested: Add one checklist item to the "adding a new target" section (or the PR template): "[ ] All commands that accept a target include a short --help example using the new target name."

Auth Expert -- inactive

No auth files in diff; help-text-only change does not touch authentication behavior, token management, credential resolution, or host classification.

Doc Writer

• [nit] update.py help text appends kiro after gemini, contradicting the documented order on the CLI reference page at src/apm_cli/commands/update.py:42
  The reference page at docs/src/content/docs/reference/cli/update.md (line 46) positions kiro between windsurf and codex. When the in-binary help text and the docs site disagree on ordering, users who cross-reference the two get inconsistent mental models.
  Suggested: Reorder to: claude, copilot, cursor, windsurf, kiro, codex, opencode, gemini -- matching the reference page order.

• [recommended] No CHANGELOG entry covers the --target help-text fix for kiro at CHANGELOG.md
  Project convention requires a ### Fixed bullet for every notable fix in [Unreleased]. The kiro target itself was introduced in v0.20.0 with a proper entry; leaving this undocumented breaks the audit trail.
  Suggested: Add to [Unreleased] under ### Fixed: - \apm update --target` help text now lists `kiro` as a valid example target, matching `apm install`. (docs(cli): list kiro in update target help #1821)`

Test Coverage Expert

• [nit] Multi-line --target section parser is brittle; one assertion is trivially true at tests/unit/test_update_command.py
  The collector loop breaks on stripped.startswith("-") and not stripped.startswith("--target") -- sensitive to Click's default 80-column layout. self.assertIn("--target", target_help) is trivially true since the first element appended is always the line starting with -t, --target. The load-bearing assertion is assertIn("kiro", target_help). Simpler and equally robust: self.assertIn("kiro", result.output) paired with self.assertIn("gemini", result.output).
  Proof (passed): tests/unit/test_update_command.py::TestUpdateCommandLogic::test_dependency_update_help_lists_kiro_target_example -- proves: apm update --help lists kiro as a valid --target example [devx]

Performance Expert -- inactive

No performance-relevant files in diff; help-text-only change does not affect dependency download, cache, transport, parallelism, or install/update wall-time.

_{This panel is advisory. It does not block merge. Re-apply the panel-review label after addressing feedback to re-run.}

Generated by PR Review Panel for issue #1821 · sonnet46 10.6M · ◷

[WilliamK112]

Thanks for the review-panel pass. I pushed a small follow-up in 7a785940 that addresses the two recommended in-PR items:

• Added the [Unreleased] / Fixed changelog entry for apm update --target listing kiro.
• Reordered the apm update --target example list to claude, copilot, cursor, windsurf, kiro, codex, opencode, gemini in both the module docs and Click help text.

Local validation on Windows / Python 3.12:

uv run --extra dev pytest tests/unit/test_update_command.py::TestUpdateCommandLogic::test_dependency_update_help_lists_kiro_target_example
uv run --extra dev ruff check src/apm_cli/commands/update.py tests/unit/test_update_command.py
uv run --extra dev ruff format --check src/apm_cli/commands/update.py tests/unit/test_update_command.py
git diff --check