feat: deprecate and replace zarf package inspect with child commands zarf package inspect definition|sbom|images

site/src/content/docs/commands/zarf_package_inspect.md

@@ -23,7 +23,6 @@ zarf package inspect [ PACKAGE_SOURCE ] [flags]
 ```
   -h, --help                        help for inspect
       --list-images                 List images in the package (prints to stdout)
-  -s, --sbom                        View SBOM contents while inspecting the package
       --sbom-out string             Specify an output directory for the SBOMs from the inspected Zarf package
       --skip-signature-validation   Skip validating the signature of the Zarf package
 ```
@@ -48,4 +47,7 @@ zarf package inspect [ PACKAGE_SOURCE ] [flags]
 ### SEE ALSO
 
 * [zarf package](/commands/zarf_package/)	 - Zarf package commands for creating, deploying, and inspecting packages
+* [zarf package inspect definition](/commands/zarf_package_inspect_definition/)	 - Displays the 'zarf.yaml' definition for the specified package
+* [zarf package inspect images](/commands/zarf_package_inspect_images/)	 - List all container images contained in the package
+* [zarf package inspect sbom](/commands/zarf_package_inspect_sbom/)	 - Output the package SBOM (Software Bill Of Materials) to the specified directory
 

site/src/content/docs/commands/zarf_package_inspect_definition.md

@@ -0,0 +1,44 @@
+---
+title: zarf package inspect definition
+description: Zarf CLI command reference for <code>zarf package inspect definition</code>.
+tableOfContents: false
+---
+
+<!-- Page generated by Zarf; DO NOT EDIT -->
+
+## zarf package inspect definition
+
+Displays the 'zarf.yaml' definition for the specified package
+
+```
+zarf package inspect definition [ PACKAGE_SOURCE ] [flags]
+```
+
+### Options
+
+```
+  -h, --help                        help for definition
+      --skip-signature-validation   Skip validating the signature of the Zarf package
+```
+
+### Options inherited from parent commands
+
+```
+  -a, --architecture string        Architecture for OCI images and Zarf packages
+      --insecure-skip-tls-verify   Skip checking server's certificate for validity. This flag should only be used if you have a specific reason and accept the reduced security posture.
+  -k, --key string                 Path to public key file for validating signed packages
+      --log-format string          [beta] Select a logging format. Defaults to 'console'. Valid options are: 'console', 'json', 'dev'
+  -l, --log-level string           Log level when running Zarf. Valid options are: warn, info, debug, trace (default "info")
+      --no-color                   Disable colors in output
+      --no-log-file                Disable log file creation
+      --no-progress                Disable fancy UI progress bars, spinners, logos, etc
+      --oci-concurrency int        Number of concurrent layer operations to perform when interacting with a remote package. (default 3)
+      --plain-http                 Force the connections over HTTP instead of HTTPS. This flag should only be used if you have a specific reason and accept the reduced security posture.
+      --tmpdir string              Specify the temporary directory to use for intermediate files
+      --zarf-cache string          Specify the location of the Zarf cache directory (default "~/.zarf-cache")
+```
+
+### SEE ALSO
+
+* [zarf package inspect](/commands/zarf_package_inspect/)	 - Displays the definition of a Zarf package (runs offline)
+

site/src/content/docs/commands/zarf_package_inspect_images.md

@@ -0,0 +1,44 @@
+---
+title: zarf package inspect images
+description: Zarf CLI command reference for <code>zarf package inspect images</code>.
+tableOfContents: false
+---
+
+<!-- Page generated by Zarf; DO NOT EDIT -->
+
+## zarf package inspect images
+
+List all container images contained in the package
+
+```
+zarf package inspect images [ PACKAGE_SOURCE ] [flags]
+```
+
+### Options
+
+```
+  -h, --help                        help for images
+      --skip-signature-validation   Skip validating the signature of the Zarf package
+```
+
+### Options inherited from parent commands
+
+```
+  -a, --architecture string        Architecture for OCI images and Zarf packages
+      --insecure-skip-tls-verify   Skip checking server's certificate for validity. This flag should only be used if you have a specific reason and accept the reduced security posture.
+  -k, --key string                 Path to public key file for validating signed packages
+      --log-format string          [beta] Select a logging format. Defaults to 'console'. Valid options are: 'console', 'json', 'dev'
+  -l, --log-level string           Log level when running Zarf. Valid options are: warn, info, debug, trace (default "info")
+      --no-color                   Disable colors in output
+      --no-log-file                Disable log file creation
+      --no-progress                Disable fancy UI progress bars, spinners, logos, etc
+      --oci-concurrency int        Number of concurrent layer operations to perform when interacting with a remote package. (default 3)
+      --plain-http                 Force the connections over HTTP instead of HTTPS. This flag should only be used if you have a specific reason and accept the reduced security posture.
+      --tmpdir string              Specify the temporary directory to use for intermediate files
+      --zarf-cache string          Specify the location of the Zarf cache directory (default "~/.zarf-cache")
+```
+
+### SEE ALSO
+
+* [zarf package inspect](/commands/zarf_package_inspect/)	 - Displays the definition of a Zarf package (runs offline)
+

site/src/content/docs/commands/zarf_package_inspect_sbom.md

@@ -0,0 +1,45 @@
+---
+title: zarf package inspect sbom
+description: Zarf CLI command reference for <code>zarf package inspect sbom</code>.
+tableOfContents: false
+---
+
+<!-- Page generated by Zarf; DO NOT EDIT -->
+
+## zarf package inspect sbom
+
+Output the package SBOM (Software Bill Of Materials) to the specified directory
+
+```
+zarf package inspect sbom [ PACKAGE ] [flags]
+```
+
+### Options
+
+```
+  -h, --help                        help for sbom
+      --output string               Specify an output directory for the SBOMs from the created Zarf package
+      --skip-signature-validation   Skip validating the signature of the Zarf package
+```
+
+### Options inherited from parent commands
+
+```
+  -a, --architecture string        Architecture for OCI images and Zarf packages
+      --insecure-skip-tls-verify   Skip checking server's certificate for validity. This flag should only be used if you have a specific reason and accept the reduced security posture.
+  -k, --key string                 Path to public key file for validating signed packages
+      --log-format string          [beta] Select a logging format. Defaults to 'console'. Valid options are: 'console', 'json', 'dev'
+  -l, --log-level string           Log level when running Zarf. Valid options are: warn, info, debug, trace (default "info")
+      --no-color                   Disable colors in output
+      --no-log-file                Disable log file creation
+      --no-progress                Disable fancy UI progress bars, spinners, logos, etc
+      --oci-concurrency int        Number of concurrent layer operations to perform when interacting with a remote package. (default 3)
+      --plain-http                 Force the connections over HTTP instead of HTTPS. This flag should only be used if you have a specific reason and accept the reduced security posture.
+      --tmpdir string              Specify the temporary directory to use for intermediate files
+      --zarf-cache string          Specify the location of the Zarf cache directory (default "~/.zarf-cache")
+```
+
+### SEE ALSO
+
+* [zarf package inspect](/commands/zarf_package_inspect/)	 - Displays the definition of a Zarf package (runs offline)
+

src/cmd/package.go

@@ -357,7 +357,10 @@ func NewPackageInspectCommand() *cobra.Command {
 		RunE:    o.Run,
 	}
 
-	cmd.Flags().BoolVarP(&pkgConfig.InspectOpts.ViewSBOM, "sbom", "s", false, lang.CmdPackageInspectFlagSbom)
+	cmd.AddCommand(newPackageInspectSBOMCommand())
+	cmd.AddCommand(newPackageInspectImagesCommand())
+	cmd.AddCommand(newPackageInspectDefinitionCommand())
+
 	cmd.Flags().StringVar(&pkgConfig.InspectOpts.SBOMOutputDir, "sbom-out", "", lang.CmdPackageInspectFlagSbomOut)
 	cmd.Flags().BoolVar(&pkgConfig.InspectOpts.ListImages, "list-images", false, lang.CmdPackageInspectFlagListImages)
 	cmd.Flags().BoolVar(&pkgConfig.PkgOpts.SkipSignatureValidation, "skip-signature-validation", false, lang.CmdPackageFlagSkipSignatureValidation)
@@ -376,47 +379,187 @@ func (o *PackageInspectOptions) PreRun(_ *cobra.Command, _ []string) {
 // Run performs the execution of 'package inspect' sub-command.
 func (o *PackageInspectOptions) Run(cmd *cobra.Command, args []string) error {
 	ctx := cmd.Context()
+	logger.From(ctx).Warn("Direct usage of inspect is deprecated and will be removed in a future release. Inspect is now a parent command. Use 'zarf package inspect definition|sbom|images' instead.")
+
+	if pkgConfig.InspectOpts.ListImages && pkgConfig.InspectOpts.SBOMOutputDir != "" {
+		return fmt.Errorf("cannot use --sbom-out and --list-images at the same time")
+	}
 
-	if pkgConfig.InspectOpts.ListImages && (pkgConfig.InspectOpts.SBOMOutputDir != "" || pkgConfig.InspectOpts.ViewSBOM) {
-		return fmt.Errorf("cannot use --sbom or --sbom-out and --list-images at the same time")
+	if pkgConfig.InspectOpts.SBOMOutputDir != "" {
+		sbomOpts := PackageInspectSBOMOptions{
+			skipSignatureValidation: pkgConfig.PkgOpts.SkipSignatureValidation,
+			outputDir:               pkgConfig.InspectOpts.SBOMOutputDir,
+		}
+		return sbomOpts.Run(cmd, args)
 	}
 
-	// NOTE(mkcp): Gets user input with message
+	if pkgConfig.InspectOpts.ListImages {
+		imagesOpts := packageInspectImagesOptions{
+			skipSignatureValidation: pkgConfig.PkgOpts.SkipSignatureValidation,
+		}
+		return imagesOpts.run(cmd, args)
+	}
+
+	definitionOpts := packageInspectDefinitionOptions{
+		skipSignatureValidation: pkgConfig.PkgOpts.SkipSignatureValidation,
+	}
+	return definitionOpts.run(cmd, args)
+}
+
+// PackageInspectSBOMOptions holds the command-line options for 'package inspect sbom' sub-command.
+type PackageInspectSBOMOptions struct {
+	skipSignatureValidation bool
+	outputDir               string
+}
+
+func newPackageInspectSBOMOptions() *PackageInspectSBOMOptions {
+	return &PackageInspectSBOMOptions{
+		outputDir:               "",
+		skipSignatureValidation: false,
+	}
+}
+
+// newPackageInspectSBOMCommand creates the `package inspect sbom` sub-command.
+func newPackageInspectSBOMCommand() *cobra.Command {
+	o := newPackageInspectSBOMOptions()
+	cmd := &cobra.Command{
+		Use:   "sbom [ PACKAGE ]",
+		Short: "Output the package SBOM (Software Bill Of Materials) to the specified directory",
+		Args:  cobra.MaximumNArgs(1),
+		RunE:  o.Run,
+	}
+
+	cmd.Flags().BoolVar(&o.skipSignatureValidation, "skip-signature-validation", o.skipSignatureValidation, lang.CmdPackageFlagSkipSignatureValidation)
+	cmd.Flags().StringVar(&o.outputDir, "output", o.outputDir, lang.CmdPackageCreateFlagSbomOut)
+
+	return cmd
+}
+
+// Run performs the execution of 'package inspect sbom' sub-command.
+func (o *PackageInspectSBOMOptions) Run(cmd *cobra.Command, args []string) error {
+	ctx := cmd.Context()
 	src, err := choosePackage(ctx, args)
 	if err != nil {
 		return err
 	}
-
-	cluster, _ := cluster.NewCluster() //nolint:errcheck
-	inspectOpt := packager2.ZarfInspectOptions{
+	loadOpt := packager2.LoadOptions{
 		Source:                  src,
-		SkipSignatureValidation: pkgConfig.PkgOpts.SkipSignatureValidation,
-		Cluster:                 cluster,
-		ListImages:              pkgConfig.InspectOpts.ListImages,
-		ViewSBOM:                pkgConfig.InspectOpts.ViewSBOM,
-		SBOMOutputDir:           pkgConfig.InspectOpts.SBOMOutputDir,
+		SkipSignatureValidation: o.skipSignatureValidation,
+		Filter:                  filters.Empty(),
 		PublicKeyPath:           pkgConfig.PkgOpts.PublicKeyPath,
 	}
-
-	if pkgConfig.InspectOpts.ListImages {
-		output, err := packager2.InspectList(ctx, inspectOpt)
-		if err != nil {
-			return fmt.Errorf("failed to inspect package: %w", err)
-		}
-		for _, image := range output {
-			_, err := fmt.Fprintln(os.Stdout, "-", image)
-			if err != nil {
-				return err
-			}
-		}
+	layout, err := packager2.LoadPackage(ctx, loadOpt)
+	if err != nil {
+		return err
+	}
+	outputPath, err := layout.GetSBOM(o.outputDir)
+	if err != nil {
+		return err
+	}
+	outputPath, err = filepath.Abs(outputPath)
+	if err != nil {
+		logger.From(ctx).Warn("SBOM successfully extracted, couldn't get output path", "error", err)
 		return nil
 	}
+	logger.From(ctx).Info("SBOM successfully extracted", "path", outputPath)
+	return nil
+}
+
+type packageInspectImagesOptions struct {
+	skipSignatureValidation bool
+}
 
-	output, err := packager2.Inspect(ctx, inspectOpt)
+func newPackageInspectImagesOptions() *packageInspectImagesOptions {
+	return &packageInspectImagesOptions{
+		skipSignatureValidation: false,
+	}
+}
+
+func newPackageInspectImagesCommand() *cobra.Command {
+	o := newPackageInspectImagesOptions()
+	cmd := &cobra.Command{
+		Use:   "images [ PACKAGE_SOURCE ]",
+		Short: "List all container images contained in the package",
+		Args:  cobra.MaximumNArgs(1),
+		RunE:  o.run,
+	}
+
+	cmd.Flags().BoolVar(&o.skipSignatureValidation, "skip-signature-validation", o.skipSignatureValidation, lang.CmdPackageFlagSkipSignatureValidation)
+
+	return cmd
+}
+
+func (o *packageInspectImagesOptions) run(cmd *cobra.Command, args []string) error {
+	ctx := cmd.Context()
+
+	src, err := choosePackage(ctx, args)
+	if err != nil {
+		return err
+	}
+
+	// The user may be pulling the package from the cluster or using a built package
+	// since we don't know we don't check this error
+	cluster, _ := cluster.NewCluster() //nolint:errcheck
+
+	pkg, err := packager2.GetPackageFromSourceOrCluster(ctx, cluster, src, o.skipSignatureValidation, pkgConfig.PkgOpts.PublicKeyPath)
+	if err != nil {
+		return err
+	}
+	var imageList []string
+	for _, component := range pkg.Components {
+		imageList = append(imageList, component.Images...)
+	}
+	if imageList == nil {
+		return fmt.Errorf("failed listing images: 0 images found in package")
+	}
+	imageList = helpers.Unique(imageList)
+	for _, image := range imageList {
+		fmt.Println("-", image)
+	}
+	return nil
+}
+
+type packageInspectDefinitionOptions struct {
+	skipSignatureValidation bool
+}
+
+func newPackageInspectDefinitionOptions() *packageInspectDefinitionOptions {
+	return &packageInspectDefinitionOptions{
+		skipSignatureValidation: false,
+	}
+}
+
+func newPackageInspectDefinitionCommand() *cobra.Command {
+	o := newPackageInspectDefinitionOptions()
+	cmd := &cobra.Command{
+		Use:   "definition [ PACKAGE_SOURCE ]",
+		Short: "Displays the 'zarf.yaml' definition for the specified package",
+		Args:  cobra.MaximumNArgs(1),
+		RunE:  o.run,
+	}
+
+	cmd.Flags().BoolVar(&o.skipSignatureValidation, "skip-signature-validation", o.skipSignatureValidation, lang.CmdPackageFlagSkipSignatureValidation)
+
+	return cmd
+}
+
+func (o *packageInspectDefinitionOptions) run(cmd *cobra.Command, args []string) error {
+	ctx := cmd.Context()
+
+	src, err := choosePackage(ctx, args)
+	if err != nil {
+		return err
+	}
+
+	// The user may be pulling the package from the cluster or using a built package
+	// since we don't know we don't check this error
+	cluster, _ := cluster.NewCluster() //nolint:errcheck
+
+	pkg, err := packager2.GetPackageFromSourceOrCluster(ctx, cluster, src, o.skipSignatureValidation, pkgConfig.PkgOpts.PublicKeyPath)
 	if err != nil {
-		return fmt.Errorf("failed to inspect package: %w", err)
+		return err
 	}
-	err = utils.ColorPrintYAML(output, nil, false)
+	err = utils.ColorPrintYAML(pkg, nil, false)
 	if err != nil {
 		return err
 	}

src/config/lang/english.go

@@ -282,7 +282,6 @@ $ zarf package mirror-resources <your-package.tar.zst> \
 	CmdPackageMirrorFlagComponents = "Comma-separated list of components to mirror.  This list will be respected regardless of a component's 'required' or 'default' status.  Globbing component names with '*' and deselecting components with a leading '-' are also supported."
 	CmdPackageMirrorFlagNoChecksum = "Turns off the addition of a checksum to image tags (as would be used by the Zarf Agent) while mirroring images."
 
-	CmdPackageInspectFlagSbom       = "View SBOM contents while inspecting the package"
 	CmdPackageInspectFlagSbomOut    = "Specify an output directory for the SBOMs from the inspected Zarf package"
 	CmdPackageInspectFlagListImages = "List images in the package (prints to stdout)"