Add mass repository grant and mass resource grant

.golangci.yaml

@@ -397,6 +397,14 @@ linters:
         # Omit embedded fields from selector expression.
         # https://staticcheck.dev/docs/checks/#QF1008
         - -QF1008
+        # The doc-comment-form family: a comment on an exported symbol must
+        # begin with its name. Off for the same reason as revive's `exported`
+        # rule above — this module is a binary, not a library, so a comment
+        # here is free-form prose rather than generated API documentation.
+        # https://staticcheck.dev/docs/checks/#ST1020
+        - -ST1020
+        - -ST1021
+        - -ST1022
 
     usetesting:
       # Enable/disable `os.TempDir()` detections.
@@ -417,6 +425,10 @@ linters:
     # Allow unused params at the cobra command level
     - linters: [revive]
       text: "unused-parameter: parameter ('cmd'|'args') seems to be unused, consider removing or renaming it as _"
+    # This module ships a CLI binary, not a library. Nothing here is importable
+    # API, so doc comments are a judgement call rather than a requirement.
+    - linters: [revive]
+      text: "^exported:"
     - path: "_test\\.go"
       linters:
         - revive

cmd/bundle.go

@@ -167,11 +167,11 @@ func NewCmdBundle() *cobra.Command { //nolint:funlen // cobra command builders a
 	bundleTemplateListCmd.Flags().StringP("output", "o", "text", "Output format (text, json)")
 
 	bundleCreateCmd := &cobra.Command{
-		Use:     "create <name>",
-		Short:   "Create a new bundle OCI repository in your organization's catalog",
-		Example: `mass bundle create aws-aurora-postgres -a owner=data,service=database`,
-		Args:    cobra.ExactArgs(1),
-		RunE:    runBundleCreate,
+		Use:   "create <name>",
+		Short: "Create a new bundle OCI repository in your organization's catalog",
+		Long:  helpdocs.MustRender("bundle/create"),
+		Args:  cobra.ExactArgs(1),
+		RunE:  runBundleCreate,
 	}
 	bundleCreateCmd.Flags().StringToStringP("attributes", "a", nil, "Custom attributes (e.g. -a owner=data,service=database)")
 

cmd/component.go

@@ -24,12 +24,11 @@ func NewCmdComponent() *cobra.Command {
 	}
 
 	componentAddCmd := &cobra.Command{
-		Use:     "add <project-id> <bundle-oci-repo-name>",
-		Short:   "Add a component to a project's blueprint",
-		Example: `mass component add ecomm aws-rds-cluster --id db --name "Primary Database"`,
-		Long:    helpdocs.MustRender("component/add"),
-		Args:    cobra.ExactArgs(2),
-		RunE:    runComponentAdd,
+		Use:   "add <project-id> <bundle-oci-repo-name>",
+		Short: "Add a component to a project's blueprint",
+		Long:  helpdocs.MustRender("component/add"),
+		Args:  cobra.ExactArgs(2),
+		RunE:  runComponentAdd,
 	}
 	componentAddCmd.Flags().String("id", "", "Short identifier for this component (e.g., db). Max 20 chars, lowercase alphanumeric.")
 	componentAddCmd.Flags().StringP("name", "n", "", "Display name (defaults to --id if not provided)")
@@ -38,11 +37,11 @@ func NewCmdComponent() *cobra.Command {
 	_ = componentAddCmd.MarkFlagRequired("id")
 
 	componentUpdateCmd := &cobra.Command{
-		Use:     "update <component-id>",
-		Short:   "Update a component's name, description, or attributes",
-		Example: `mass component update ecomm-db --name "Primary DB" -a priority=high`,
-		Args:    cobra.ExactArgs(1),
-		RunE:    runComponentUpdate,
+		Use:   "update <component-id>",
+		Short: "Update a component's name, description, or attributes",
+		Long:  helpdocs.MustRender("component/update"),
+		Args:  cobra.ExactArgs(1),
+		RunE:  runComponentUpdate,
 	}
 	componentUpdateCmd.Flags().StringP("name", "n", "", "New display name")
 	componentUpdateCmd.Flags().StringP("description", "d", "", "New description")
@@ -52,30 +51,27 @@ func NewCmdComponent() *cobra.Command {
 		Use:     "remove <component-id>",
 		Aliases: []string{"rm"},
 		Short:   "Remove a component from a project's blueprint",
-		Example: `mass component remove ecomm-db`,
 		Long:    helpdocs.MustRender("component/remove"),
 		Args:    cobra.ExactArgs(1),
 		RunE:    runComponentRemove,
 	}
 
 	componentLinkCmd := &cobra.Command{
-		Use:     "link <from-component>.<from-field> <to-component>.<to-field>",
-		Short:   "Link two components in a project's blueprint",
-		Example: `mass component link ecomm-db.authentication ecomm-app.database --from-version ~1.0 --to-version ~2.0`,
-		Long:    helpdocs.MustRender("component/link"),
-		Args:    cobra.ExactArgs(2),
-		RunE:    runComponentLink,
+		Use:   "link <from-component>.<from-field> <to-component>.<to-field>",
+		Short: "Link two components in a project's blueprint",
+		Long:  helpdocs.MustRender("component/link"),
+		Args:  cobra.ExactArgs(2),
+		RunE:  runComponentLink,
 	}
 	componentLinkCmd.Flags().String("from-version", "latest", "Version constraint for the source component")
 	componentLinkCmd.Flags().String("to-version", "latest", "Version constraint for the destination component")
 
 	componentUnlinkCmd := &cobra.Command{
-		Use:     "unlink <from-component>.<from-field> <to-component>.<to-field>",
-		Short:   "Remove a link between two components",
-		Example: `mass component unlink ecomm-db.authentication ecomm-app.database`,
-		Long:    helpdocs.MustRender("component/unlink"),
-		Args:    cobra.ExactArgs(2),
-		RunE:    runComponentUnlink,
+		Use:   "unlink <from-component>.<from-field> <to-component>.<to-field>",
+		Short: "Remove a link between two components",
+		Long:  helpdocs.MustRender("component/unlink"),
+		Args:  cobra.ExactArgs(2),
+		RunE:  runComponentUnlink,
 	}
 
 	componentCmd.AddCommand(componentAddCmd)

cmd/deployment.go

@@ -38,20 +38,18 @@ func NewCmdDeployment() *cobra.Command {
 	}
 
 	deploymentGetCmd := &cobra.Command{
-		Use:     "get <deployment-id>",
-		Short:   "Get a deployment by ID",
-		Example: `mass deployment get 12345678-1234-1234-1234-123456789012`,
-		Long:    helpdocs.MustRender("deployment/get"),
-		Args:    cobra.ExactArgs(1),
-		RunE:    runDeploymentGet,
+		Use:   "get <deployment-id>",
+		Short: "Get a deployment by ID",
+		Long:  helpdocs.MustRender("deployment/get"),
+		Args:  cobra.ExactArgs(1),
+		RunE:  runDeploymentGet,
 	}
 	deploymentGetCmd.Flags().StringP("output", "o", "text", "Output format (text or json)")
 
 	deploymentListCmd := &cobra.Command{
 		Use:     "list <instance-id>",
 		Aliases: []string{"ls"},
 		Short:   "List deployments for an instance (most recent first)",
-		Example: `mass deployment list ecomm-prod-db --limit 25`,
 		Long:    helpdocs.MustRender("deployment/list"),
 		Args:    cobra.ExactArgs(1),
 		RunE:    runDeploymentList,
@@ -64,47 +62,42 @@ func NewCmdDeployment() *cobra.Command {
 	deploymentListCmd.Flags().String("bundle", "", "Filter by bundle version (name@version) or release channel (name@latest)")
 
 	deploymentLogsCmd := &cobra.Command{
-		Use:     "logs <deployment-id>",
-		Short:   "Stream the log output from a deployment",
-		Example: `mass deployment logs 12345678-1234-1234-1234-123456789012`,
-		Long:    helpdocs.MustRender("deployment/logs"),
-		Args:    cobra.ExactArgs(1),
-		RunE:    runDeploymentLogs,
+		Use:   "logs <deployment-id>",
+		Short: "Stream the log output from a deployment",
+		Long:  helpdocs.MustRender("deployment/logs"),
+		Args:  cobra.ExactArgs(1),
+		RunE:  runDeploymentLogs,
 	}
 
 	deploymentAbortCmd := &cobra.Command{
-		Use:     "abort <deployment-id>",
-		Short:   "Abort a pending, approved, or running deployment",
-		Example: `mass deployment abort 12345678-1234-1234-1234-123456789012 --force`,
-		Long:    helpdocs.MustRender("deployment/abort"),
-		Args:    cobra.ExactArgs(1),
-		RunE:    runDeploymentAbort,
+		Use:   "abort <deployment-id>",
+		Short: "Abort a pending, approved, or running deployment",
+		Long:  helpdocs.MustRender("deployment/abort"),
+		Args:  cobra.ExactArgs(1),
+		RunE:  runDeploymentAbort,
 	}
 	deploymentAbortCmd.Flags().BoolP("force", "f", false, "Skip confirmation prompt")
 
 	deploymentApproveCmd := &cobra.Command{
-		Use:     "approve <deployment-id>",
-		Short:   "Approve a proposed deployment, releasing it to run",
-		Example: `mass deployment approve 12345678-1234-1234-1234-123456789012`,
-		Long:    helpdocs.MustRender("deployment/approve"),
-		Args:    cobra.ExactArgs(1),
-		RunE:    runDeploymentApprove,
+		Use:   "approve <deployment-id>",
+		Short: "Approve a proposed deployment, releasing it to run",
+		Long:  helpdocs.MustRender("deployment/approve"),
+		Args:  cobra.ExactArgs(1),
+		RunE:  runDeploymentApprove,
 	}
 
 	deploymentRejectCmd := &cobra.Command{
-		Use:     "reject <deployment-id>",
-		Short:   "Reject a proposed deployment, discarding it permanently",
-		Example: `mass deployment reject 12345678-1234-1234-1234-123456789012`,
-		Long:    helpdocs.MustRender("deployment/reject"),
-		Args:    cobra.ExactArgs(1),
-		RunE:    runDeploymentReject,
+		Use:   "reject <deployment-id>",
+		Short: "Reject a proposed deployment, discarding it permanently",
+		Long:  helpdocs.MustRender("deployment/reject"),
+		Args:  cobra.ExactArgs(1),
+		RunE:  runDeploymentReject,
 	}
 
 	deploymentCompareCmd := &cobra.Command{
 		Use:     "compare <source-deployment-id> <target-deployment-id>",
 		Aliases: []string{"diff"},
 		Short:   "Compare two deployments' bundle version and params",
-		Example: `mass deployment compare 1111... 2222...`,
 		Long:    helpdocs.MustRender("deployment/compare"),
 		Args:    cobra.ExactArgs(2),
 		RunE:    runDeploymentCompare,

cmd/environment.go

@@ -110,12 +110,11 @@ func NewCmdEnvironment() *cobra.Command {
 
 func newEnvironmentDeleteCmd() *cobra.Command {
 	c := &cobra.Command{
-		Use:     "delete [environment]",
-		Short:   "Delete an environment",
-		Example: `mass environment delete ecomm-staging`,
-		Long:    helpdocs.MustRender("environment/delete"),
-		Args:    cobra.ExactArgs(1),
-		RunE:    runEnvironmentDelete,
+		Use:   "delete [environment]",
+		Short: "Delete an environment",
+		Long:  helpdocs.MustRender("environment/delete"),
+		Args:  cobra.ExactArgs(1),
+		RunE:  runEnvironmentDelete,
 	}
 	c.Flags().BoolP("force", "f", false, "Skip confirmation prompt")
 	return c
@@ -126,7 +125,6 @@ func newEnvironmentCompareCmd() *cobra.Command {
 		Use:     "compare [source-environment] [target-environment]",
 		Aliases: []string{"diff"},
 		Short:   "Compare two environments instance-by-instance",
-		Example: `mass environment compare ecomm-staging ecomm-production`,
 		Long:    helpdocs.MustRender("environment/compare"),
 		Args:    cobra.ExactArgs(2),
 		RunE:    runEnvironmentCompare,
@@ -154,12 +152,11 @@ func newEnvironmentPreviewCmd() *cobra.Command {
 
 func newEnvironmentForkCmd() *cobra.Command {
 	c := &cobra.Command{
-		Use:     "fork [parent-environment] [new-ID]",
-		Short:   "Fork an existing environment",
-		Example: `mass environment fork ecomm-production staging`,
-		Long:    helpdocs.MustRender("environment/fork"),
-		Args:    cobra.ExactArgs(2),
-		RunE:    runEnvironmentFork,
+		Use:   "fork [parent-environment] [new-ID]",
+		Short: "Fork an existing environment",
+		Long:  helpdocs.MustRender("environment/fork"),
+		Args:  cobra.ExactArgs(2),
+		RunE:  runEnvironmentFork,
 	}
 	c.Flags().StringP("name", "n", "", "Environment name (defaults to new-ID if not provided)")
 	c.Flags().StringP("description", "d", "", "Optional environment description")
@@ -172,25 +169,23 @@ func newEnvironmentForkCmd() *cobra.Command {
 
 func newEnvironmentDeployCmd() *cobra.Command {
 	c := &cobra.Command{
-		Use:     "deploy [environment]",
-		Short:   "Deploy every instance in an environment, in dependency order",
-		Example: `mass environment deploy ecomm-staging --follow`,
-		Long:    helpdocs.MustRender("environment/deploy"),
-		Args:    cobra.ExactArgs(1),
-		RunE:    runEnvironmentDeploy,
+		Use:   "deploy [environment]",
+		Short: "Deploy every instance in an environment, in dependency order",
+		Long:  helpdocs.MustRender("environment/deploy"),
+		Args:  cobra.ExactArgs(1),
+		RunE:  runEnvironmentDeploy,
 	}
 	c.Flags().Bool("follow", false, "Stream every deployment's logs to stdout until the rollout completes. Each line is prefixed with the instance id.")
 	return c
 }
 
 func newEnvironmentDecommissionCmd() *cobra.Command {
 	c := &cobra.Command{
-		Use:     "decommission [environment]",
-		Short:   "Decommission every instance in an environment, in reverse dependency order",
-		Example: `mass environment decommission ecomm-pr42 --follow`,
-		Long:    helpdocs.MustRender("environment/decommission"),
-		Args:    cobra.ExactArgs(1),
-		RunE:    runEnvironmentDecommission,
+		Use:   "decommission [environment]",
+		Short: "Decommission every instance in an environment, in reverse dependency order",
+		Long:  helpdocs.MustRender("environment/decommission"),
+		Args:  cobra.ExactArgs(1),
+		RunE:  runEnvironmentDecommission,
 	}
 	c.Flags().Bool("follow", false, "Stream every decommission deployment's logs to stdout until the rollout completes. Each line is prefixed with the instance id.")
 	return c