RTECO-1648 - Implement jf agent apm command

agent/apm/cli/cli.go

@@ -0,0 +1,46 @@
+package cli
+
+import (
+	"github.com/jfrog/jfrog-cli-artifactory/agent/apm/commands/install"
+	"github.com/jfrog/jfrog-cli-artifactory/agent/apm/commands/publish"
+	"github.com/jfrog/jfrog-cli-artifactory/agent/apm/commands/update"
+	"github.com/jfrog/jfrog-cli-artifactory/cliutils/flagkit"
+	"github.com/jfrog/jfrog-cli-core/v2/plugins/components"
+)
+
+// GetSubCommands returns the leaf commands for `jf agent apm`.
+// Commands not listed here fall through to the passthrough handler set on the parent.
+// "lock" is deliberately not listed here — it doesn't deploy anything, so there's nothing
+// a build actually consumed to report; it's served by the generic passthrough like every
+// other read/resolve-only apm command.
+func GetSubCommands() []components.Command {
+	return []components.Command{
+		{
+			Name:  "install",
+			Flags: flagkit.GetCommandFlags(flagkit.AgentApm),
+			// SkipFlagParsing so apm-native flags (e.g. --frozen) that aren't in jf's own
+			// declared flag set above aren't rejected by urfave/cli before reaching apm.
+			// RunInstall extracts jf's own flags manually via ExtractApmSubcommandOptions.
+			SkipFlagParsing: true,
+			Description:     "Install APM packages with JFrog Artifactory authentication.",
+			AIDescription:   install.GetAIDescription(),
+			Action:          install.RunInstall,
+		},
+		{
+			Name:            "publish",
+			Flags:           flagkit.GetCommandFlags(flagkit.AgentApm),
+			SkipFlagParsing: true,
+			Description:     "Publish an APM package to JFrog Artifactory.",
+			AIDescription:   publish.GetAIDescription(),
+			Action:          publish.RunPublish,
+		},
+		{
+			Name:            "update",
+			Flags:           flagkit.GetCommandFlags(flagkit.AgentApm),
+			SkipFlagParsing: true,
+			Description:     "Refresh APM dependencies to their latest matching refs, with build-info collection.",
+			AIDescription:   update.GetAIDescription(),
+			Action:          update.RunUpdate,
+		},
+	}
+}

agent/apm/commands/install/help.go

@@ -0,0 +1,35 @@
+package install
+
+func GetDescription() string {
+	return "Install APM packages with JFrog Artifactory authentication."
+}
+
+func GetAIDescription() string {
+	return `Install packages declared in apm.yml with authenticated access to JFrog Artifactory registries.
+
+When to use:
+- Installing packages into an agent project that has apm.yml configured.
+- Accessing private or curated packages from Artifactory via registry credentials.
+- Collecting build-info about package dependencies in CI/CD pipelines.
+
+Prerequisites:
+- apm CLI (>= 0.1.0) installed and in PATH.
+- A registry declared in apm.yml's registries: block or configured via jf setup agent-apm.
+- Read permission on the source Artifactory agentpackages repository.
+
+Common patterns:
+  $ jf agent apm install
+  $ jf agent apm install --build-name=my-build --build-number=1
+
+Build info:
+- Enabled with --build-name and --build-number flags.
+- Captures installed packages and their transitive dependencies.
+- Published to Artifactory for traceability and compliance.
+
+Environment:
+- Credentials injected via APM_REGISTRY_TOKEN_<NAME>, APM_REGISTRY_USER_<NAME>, APM_REGISTRY_PASS_<NAME>.
+- Registry configuration sourced from ~/.apm/config.json (set by jf setup agent-apm).
+- Lockfile apm.lock.yaml created in working directory.
+
+Related: jf agent apm publish, jf agent apm update, jf setup agent-apm`
+}

agent/apm/commands/install/install.go

@@ -0,0 +1,101 @@
+package install
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+
+	apmcommon "github.com/jfrog/jfrog-cli-artifactory/agent/apm/common"
+	agentcommon "github.com/jfrog/jfrog-cli-artifactory/agent/common"
+	buildUtils "github.com/jfrog/jfrog-cli-core/v2/common/build"
+	"github.com/jfrog/jfrog-cli-core/v2/common/commands"
+	"github.com/jfrog/jfrog-cli-core/v2/plugins/components"
+	"github.com/jfrog/jfrog-cli-core/v2/utils/config"
+	"github.com/jfrog/jfrog-client-go/utils/log"
+)
+
+// ApmInstallCommand runs `apm install` with JFrog Artifactory authentication and collects
+// build-info from the resulting apm.lock.yaml.
+//
+// Unlike passthrough commands, install never accepts --repo: no other package-manager
+// integration in this CLI supports declaring a new repository at run time either - they all
+// require the one-time `jf setup <tool>` step first (§3, "jf setup agent-apm"). A registry
+// must already be declared (via jf setup agent-apm or apm.yml's own registries: block) before
+// install can authenticate against it.
+type ApmInstallCommand struct {
+	args               []string
+	serverDetails      *config.ServerDetails
+	buildConfiguration *buildUtils.BuildConfiguration
+}
+
+func NewApmInstallCommand() *ApmInstallCommand {
+	return &ApmInstallCommand{}
+}
+
+func (c *ApmInstallCommand) SetArgs(args []string) *ApmInstallCommand {
+	c.args = args
+	return c
+}
+
+func (c *ApmInstallCommand) SetServerDetails(serverDetails *config.ServerDetails) *ApmInstallCommand {
+	c.serverDetails = serverDetails
+	return c
+}
+
+func (c *ApmInstallCommand) SetBuildConfiguration(buildConfiguration *buildUtils.BuildConfiguration) *ApmInstallCommand {
+	c.buildConfiguration = buildConfiguration
+	return c
+}
+
+func (c *ApmInstallCommand) CommandName() string {
+	return "rt_agent_apm_install"
+}
+
+func (c *ApmInstallCommand) ServerDetails() (*config.ServerDetails, error) {
+	return c.serverDetails, nil
+}
+
+func (c *ApmInstallCommand) Run() error {
+	log.Info("Running apm install...")
+
+	if err := apmcommon.RunApmSubcommandWithAuth("install", c.args, c.serverDetails); err != nil {
+		return fmt.Errorf("run apm install: %w", err)
+	}
+
+	workingDir, err := os.Getwd()
+	if err != nil {
+		log.Warn("apm install completed, but could not determine working directory for build info:", err.Error())
+	} else {
+		lockfilePath := filepath.Join(workingDir, apmcommon.ApmLockfileName)
+		manifestPath := filepath.Join(workingDir, apmcommon.ApmManifestName)
+		if biErr := apmcommon.CollectAndSaveInstallBuildInfo(lockfilePath, manifestPath, c.serverDetails, c.buildConfiguration); biErr != nil {
+			log.Warn("apm install completed, but build info collection failed:", biErr.Error())
+		}
+	}
+
+	log.Info("apm install finished successfully.")
+	return nil
+}
+
+// RunInstall is the CLI action handler for `jf agent apm install`.
+func RunInstall(c *components.Context) error {
+	if apmcommon.IsHelpRequest(c.Arguments) {
+		return apmcommon.RunApmCommand(nil, "install", []string{"--help"})
+	}
+
+	opts, err := apmcommon.ExtractApmSubcommandOptions(c.Arguments)
+	if err != nil {
+		return err
+	}
+	serverDetails, err := agentcommon.GetServerDetails(c)
+	if err != nil {
+		return err
+	}
+
+	cmd := NewApmInstallCommand().
+		SetArgs(opts.RemainingArgs).
+		SetServerDetails(serverDetails).
+		SetBuildConfiguration(opts.BuildConfig)
+
+	return commands.ExecWithPackageManager(cmd, "agent-apm")
+}

agent/apm/commands/passthrough/passthrough.go

@@ -0,0 +1,77 @@
+package passthrough
+
+import (
+	apmcommon "github.com/jfrog/jfrog-cli-artifactory/agent/apm/common"
+	agentcommon "github.com/jfrog/jfrog-cli-artifactory/agent/common"
+	"github.com/jfrog/jfrog-cli-core/v2/common/commands"
+	"github.com/jfrog/jfrog-cli-core/v2/plugins/components"
+	"github.com/jfrog/jfrog-cli-core/v2/utils/config"
+	"github.com/jfrog/jfrog-client-go/utils/log"
+)
+
+// ApmPassthroughCommand forwards any apm subcommand with auth environment injected.
+type ApmPassthroughCommand struct {
+	subcmd        string
+	args          []string
+	serverDetails *config.ServerDetails
+}
+
+func NewApmPassthroughCommand() *ApmPassthroughCommand {
+	return &ApmPassthroughCommand{}
+}
+
+func (c *ApmPassthroughCommand) SetSubcmd(subcmd string) *ApmPassthroughCommand {
+	c.subcmd = subcmd
+	return c
+}
+
+func (c *ApmPassthroughCommand) SetArgs(args []string) *ApmPassthroughCommand {
+	c.args = args
+	return c
+}
+
+func (c *ApmPassthroughCommand) SetServerDetails(serverDetails *config.ServerDetails) *ApmPassthroughCommand {
+	c.serverDetails = serverDetails
+	return c
+}
+
+func (c *ApmPassthroughCommand) CommandName() string {
+	return "rt_agent_apm_" + c.subcmd
+}
+
+func (c *ApmPassthroughCommand) ServerDetails() (*config.ServerDetails, error) {
+	return c.serverDetails, nil
+}
+
+func (c *ApmPassthroughCommand) Run() error {
+	log.Info("Running apm " + c.subcmd + "...")
+	return apmcommon.RunApmSubcommandWithAuth(c.subcmd, c.args, c.serverDetails)
+}
+
+// RunApmPassthroughDefault handles any `jf agent apm <subcmd>` where <subcmd> is not one of the
+// registered subcommands (install/publish/update). The subcmd is the first element of
+// c.Arguments; every remaining element is forwarded to apm untouched. Auth always comes from
+// the default configured JFrog server - passthrough takes no flags of its own at all, so there's
+// nothing to extract from c.Arguments.
+func RunApmPassthroughDefault(c *components.Context) error {
+	if len(c.Arguments) == 0 {
+		return apmcommon.RunApmCommand(nil, "--help", nil)
+	}
+
+	subcmd := c.Arguments[0]
+	if apmcommon.IsHelpRequest([]string{subcmd}) {
+		return apmcommon.RunApmCommand(nil, "--help", nil)
+	}
+
+	serverDetails, err := agentcommon.GetServerDetails(c)
+	if err != nil {
+		return err
+	}
+
+	cmd := NewApmPassthroughCommand().
+		SetSubcmd(subcmd).
+		SetArgs(c.Arguments[1:]).
+		SetServerDetails(serverDetails)
+
+	return commands.ExecWithPackageManager(cmd, "agent-apm")
+}

agent/apm/commands/publish/help.go

@@ -0,0 +1,42 @@
+package publish
+
+func GetDescription() string {
+	return "Publish an APM package to JFrog Artifactory."
+}
+
+func GetAIDescription() string {
+	return `Publish an agent package to a JFrog Artifactory agentpackages repository with authenticated access.
+
+When to use:
+- Publishing custom agent packages for installation across multiple projects.
+- Packaging skills, tools, or other agent extensions for organizational use.
+- Creating reproducible, versioned deployments of agent components.
+
+Prerequisites:
+- apm CLI (>= 0.1.0) installed and in PATH.
+- An apm.yml file in the package directory (or parent directories).
+- Write permission on the Artifactory agentpackages repository.
+- Registry configured via jf setup agent-apm or apm.yml's registries: block.
+
+Common patterns:
+  $ jf agent apm publish my-org/my-package
+  $ jf agent apm publish my-org/my-package --build-name=my-build --build-number=1
+  $ jf agent apm publish my-org/my-package --build-name=my-build --build-number=1 --module=my-module
+
+Package format:
+- Directory with apm.yml declaring name, version, and description.
+- Optional skills/ subdirectory containing Cursor Agent Skills.
+- Version in apm.yml becomes the published package version.
+
+Build info:
+- Enabled with --build-name and --build-number flags.
+- Captures package metadata and publishing source.
+- Published to Artifactory for traceability and compliance.
+- Optional --module to group multiple packages in the same build.
+
+Environment:
+- Credentials injected via APM_REGISTRY_TOKEN_<NAME>, APM_REGISTRY_USER_<NAME>, APM_REGISTRY_PASS_<NAME>.
+- Registry configuration sourced from ~/.apm/config.json (set by jf setup agent-apm).
+
+Related: jf agent apm install, jf agent apm update, jf setup agent-apm`
+}