feat(no-ticket): add Maven shell-plugin credential helper

[cloudsmith-iduffy]

Description

Adds a Maven credential helper to the CLI. Maven has no native credential-helper protocol, so this uses a shell-plugin approach: a mvn shim (placed first on PATH via cloudsmith credential-helper shell-init) transparently forwards to cloudsmith exec -- mvn …, which provisions an ephemeral settings.xml from the resolved credential (API key or OIDC), runs the real mvn, and cleans up afterwards.

Highlights:

• cloudsmith exec — a generic, top-level command that runs any command with Cloudsmith credentials provisioned for it; the package manager is inferred from the command (no format argument), and commands with no integration run unchanged. Plus credential-helper shell-init and install maven (with --repo / --server-id).
• A single injected <server> authenticates both dependency resolution (download CDN) and distributionManagement (native Maven upload) — Maven matches it by <id>, not host.
• Custom-domain aware, generically: a reusable common.repo_path_segment helper org-scopes Cloudsmith URLs (a custom domain is bound to one org, so the <org> path segment is dropped; the *.cloudsmith.io defaults keep it). Used by both the download and upload URLs.
• settings.xml lives in cloudsmith_cli/templates/maven_settings.xml.tmpl (real XML, editor-validated) and is rendered via the shared templates.render() extracted in refactor(no-ticket): extract shared templates.render() from webserver #329 (stacked base PR).
• Shell-plugin state (package-managers.ini, shims) lives in the CLI config dir (get_default_config_path()), consistent with the custom-domain cache.
• Built test-first: full suite (552) and pre-commit hooks green.

Proven end-to-end with GitHub OIDC (no API key anywhere) — install, build (download), and a native mvn clean deploy (upload), with ~/.m2 caching:

• Example workflow: https://github.com/cloudsmith-iduffy/cloudsmith-cli-oidc-test/blob/main/.github/workflows/maven-oidc.yml
• Successful run logs: https://github.com/cloudsmith-iduffy/cloudsmith-cli-oidc-test/actions/runs/27446939107/job/81133936145#step:5:1

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Refactoring
• Other (please describe)

Additional Notes

• The linked test-repo workflow doubles as a real-world usage example and a living smoke test (OIDC auth, custom-domain discovery, dependency caching). The whole Cloudsmith story is three bare commands: install maven, eval "$(… shell-init)", mvn clean deploy.
• New subpackages and the template file are picked up by find_packages / existing package_data; no packaging changes needed.

[cloudsmith-iduffy]

@claude review once

[cloudsmith-iduffy]

Review (requested via @claude review once)

Overview

The PR adds a Maven credential helper built on a shell-plugin approach: an mvn shim (first on PATH via credential-helper shell-init) forwards to cloudsmith exec -- mvn …, which provisions an ephemeral 0600 settings.xml (API key or OIDC), runs the real mvn (resolved with the shims dir excluded to prevent recursion), and cleans up. The layering is clean — shellplugin (generic protocol/runner/config/shims) vs maven (format specifics) — and the test coverage is thorough (config round-trips, XML escaping, org-scoping of custom domains, provisioning failure cleanup, dry-run, PATH warnings, CLI wiring).

Issues found — fixed in b7a91dc

1. install maven accepted a missing --org (manage.py only validated --repo), producing malformed empty-org URLs like https://dl.cloudsmith.io/basic//prod/maven/ and a configured maven for None/prod action line. Now errors clearly, matching the message that already said "(and --org)".
2. cloudsmith exec --org/--repo were silently ignored once a stored binding existed — runner._resolve_entry returned the package-managers.ini entry unconditionally, so the documented flags had no effect after install maven. Explicit flags now override the stored owner/repo for that invocation.
3. Stale plugins.json references in test docstrings (the state file is package-managers.ini) — renamed; also fixed in the PR description.

Notes, no action needed

• _needs_auth matches help/--version anywhere in the argv; documented as intentional and the failure mode (skipping auth on an odd mvn … help combo) is benign for these flags.
• The security posture is sound: token only ever lands in a 0600 file inside a private mkdtemp dir, XML-escaped, removed after the child exits (including on provisioning failure); it never appears in argv or env.
• --bin-dir is accepted-but-inert for shell-plugin helpers (shims live in a fixed dir); a comment + test pin this down. Worth a warning some day if it confuses anyone.
• Windows: shims reuse write_launcher (which emits .cmd there), but shell-init only speaks bash/zsh/fish — PowerShell users would need to add the shims dir to PATH manually. Fine to defer.

Full suite + pre-commit green after the fixes. LGTM — marking ready for review.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds a Maven “shell-plugin” credential helper implemented via cloudsmith exec + PATH shims, allowing Maven commands to run with ephemeral, per-invocation Cloudsmith credentials (API key or OIDC) and generated Maven configuration.

Changes:

• Introduces cloudsmith exec plus a shell-init mechanism that prepends a shims directory to PATH so mvn invocations are transparently wrapped.
• Implements the shell-plugin framework (persistent config, shim writing, plugin registry/runner) and a Maven plugin that provisions a temporary settings.xml.
• Adds Maven installer support (including custom-domain discovery) and a comprehensive test suite covering config, runner, shims, installer, and CLI wiring.

Reviewed changes

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

Show a summary per file

File	Description
cloudsmith_cli/templates/maven_settings.xml.tmpl	New Maven settings.xml template with placeholder markers for server/token/URL.
cloudsmith_cli/templates/maven_distribution_management.xml.tmpl	New distributionManagement snippet template for Maven deploy configuration.
cloudsmith_cli/templates/init.py	Adds shared template path + placeholder rendering utility.
cloudsmith_cli/credential_helpers/shellplugin/shims.py	Writes/removes shims that forward to cloudsmith exec.
cloudsmith_cli/credential_helpers/shellplugin/shellinit.py	Emits shell init snippets to put shims dir first on PATH.
cloudsmith_cli/credential_helpers/shellplugin/runner.py	Core execution wrapper: resolves real binary, provisions creds via plugin, runs child, cleans up.
cloudsmith_cli/credential_helpers/shellplugin/plugin.py	Defines shell-plugin protocol + registry lookup by name/binary.
cloudsmith_cli/credential_helpers/shellplugin/maven.py	Maven plugin: generates ephemeral settings.xml and prepends -s <path>.
cloudsmith_cli/credential_helpers/shellplugin/config.py	Persists per-plugin bindings/hosts/ids in package-managers.ini; defines shims dir.
cloudsmith_cli/credential_helpers/shellplugin/init.py	Declares shellplugin package.
cloudsmith_cli/credential_helpers/maven/installer.py	Maven helper installer: domain discovery, shim install, config persistence, deploy snippet output.
cloudsmith_cli/credential_helpers/maven/init.py	Declares Maven helper package.
cloudsmith_cli/credential_helpers/common.py	Adds standard-host detection + repo path segment helper; reuses in domain checks.
cloudsmith_cli/cli/webserver.py	Switches webserver template rendering to the shared templates module.
cloudsmith_cli/cli/tests/commands/test_credential_helper_maven.py	Extensive tests for Maven helper: config, runner, shims, shell-init, installer, and CLI wiring.
cloudsmith_cli/cli/commands/exec_.py	Adds cloudsmith exec command wiring to shellplugin runner.
cloudsmith_cli/cli/commands/credential_helper/shell.py	Adds credential-helper shell-init command.
cloudsmith_cli/cli/commands/credential_helper/manage.py	Extends helper management to support Maven, repo binding, and registry id.
cloudsmith_cli/cli/commands/credential_helper/init.py	Registers shell-init under credential-helper.
cloudsmith_cli/cli/commands/init.py	Registers the new exec_ command module for CLI import-time registration.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.