Stop and tell the user when an AppMap tool cannot be installed

[kgilpin]

Why

When the AppMap CLI, the Java agent, or a build plugin could not be downloaded, the agent kept trying other routes (npm, other URLs, older versions, changed registry settings). We want it to stop and hand the problem back to the user.

The skills listed the recommended install methods, but never said the list was complete, and never said what to do when an install fails. Setup also told the agent to install an IDE extension and open the project, which an agent should not do.

What changed

File	Change
appmap-setup/SKILL.md Phase 0	One source per tool, in a table, and the list is said to be complete. Adds a stop rule, a list of things not to try, and what to report to the user.
appmap-record/SKILL.md	New "If a tool is missing" section.
appmap-record/languages/java.md	Drops "available from Maven Central". Names the releases pages for the agent jar and both plugins. Says where the Gradle version number comes from.
appmap-record/languages/ruby.md, python.md, node.md	The install command, and a rule that the package must come from RubyGems, PyPI, or npm.
appmap-gold-traces/SKILL.md, appmap-review/SKILL.md	Short pointer back to Phase 0.
review.mjs, manage.mjs	Error messages name the failed dependency and nothing more. Setup instructions live in the skills.

How the agent gets the CLI and the Java agent

check ~/.appmap/bin/appmap (and appmap.jar for Java)
        |
   present and new enough? -- yes --> carry on
        |
        no
        |
   download from the named release source, verify sha256,
   install to ~/.appmap, tell the user what was installed and where
        |
   worked? -- yes --> carry on
        |
        no
        |
   stop and tell the user

The agent never installs an IDE extension or launches an IDE. The extension is mentioned only as a reason the tools may already be present, and as something the user can choose to do.

Files go where the IDE extension puts them, so the Phase 0 check passes afterward:

~/.appmap/bin/appmap           -> ~/.appmap/lib/appmap/appmap-v<version>
~/.appmap/lib/java/appmap.jar  -> ~/.appmap/lib/java/appmap-<version>.jar

Before, the CLI was put "on PATH as appmap", and there was no supported way to get the Java agent jar without an IDE.

Sources

Tool	Source
AppMap CLI	the appmap-js release manifest
Java agent	appmap-java releases, checked against the sha256 the GitHub API reports
Maven and Gradle plugins	resolved by the build tool; releases pages give the version number
Ruby, Python, Node agents	RubyGems, PyPI, npm only, through the project's package manager

For review

The skills do not tell the agent to load a Maven or Gradle plugin jar into a build by hand. If the build tool cannot download the plugin, the agent stops and tells the user the jar is on the releases page, so they can add it to their internal repository.

Testing

All helper tests pass (87 of 87).

🤖 Generated with Claude Code