W-16449733 fix: clarify help docs and command output for package-name flag

messages/retrieve.start.md

@@ -103,7 +103,11 @@ Metadata component names to retrieve. Wildcards (`*`) supported as long as you u
 
 # flags.package-name.summary
 
-Package names to retrieve.
+Package names to retrieve. Use of this flag is for reference only; don't use it to retrieve packaged metadata for development.
+
+# flags.package-name.description
+
+The metadata of the supplied package name(s) will be retrieved into a child directory of the project. The name of that child directory matches the name of the package. The retrieved metadata is meant for your reference only, don't add it to a source control system for development and deployment. For package development, retrieve the metadata using a manifest (`--manifest` flag) or by targeting a source controlled package directory within your project (`--source-dir` flag).
 
 # flags.source-dir.summary
 

src/commands/project/retrieve/start.ts

@@ -77,6 +77,7 @@ export default class RetrieveMetadata extends SfCommand<RetrieveResultJson> {
     'package-name': Flags.string({
       char: 'n',
       summary: messages.getMessage('flags.package-name.summary'),
+      description: messages.getMessage('flags.package-name.description'),
       multiple: true,
     }),
     'output-dir': Flags.directory({

src/formatters/retrieveResultFormatter.ts

@@ -80,9 +80,9 @@ export class RetrieveResultFormatter implements Formatter<RetrieveResultJson> {
         name: { header: 'Package Name' },
         fullPath: { header: 'Converted Location' },
       };
-      const title = 'Retrieved Packages';
-      const options = { title: tableHeader(title), 'no-truncate': true };
+      const options = { title: tableHeader('Retrieved Packages'), 'no-truncate': true };
       this.ux.log();
+      this.ux.warn('Metadata from retrieved packages is meant for your reference only, not development.');
       this.ux.table(packages, columns, options);
     }
   }

test/commands/retrieve/start.test.ts

@@ -38,6 +38,7 @@ describe('project retrieve start', () => {
   const testOrg = new MockTestOrgData();
   testOrg.tracksSource = true;
   let sfCommandUxStubs: ReturnType<typeof stubSfCommandUx>;
+  let uxStubs: ReturnType<typeof stubUx>;
 
   testOrg.username = '[email protected]';
   const packageXml = 'package.xml';
@@ -71,7 +72,7 @@ describe('project retrieve start', () => {
     );
 
     sfCommandUxStubs = stubSfCommandUx($$.SANDBOX);
-    stubUx($$.SANDBOX);
+    uxStubs = stubUx($$.SANDBOX);
     stubSpinner($$.SANDBOX);
     $$.setConfigStubContents('SfProjectJson', {
       contents: {
@@ -250,6 +251,13 @@ describe('project retrieve start', () => {
     ensureRetrieveArgs({ packageOptions: packagenames, format: 'source' });
   });
 
+  it('should display warning when using package-name flag', async () => {
+    await RetrieveMetadata.run(['--package-name', 'package1']);
+    expect(uxStubs.warn.firstCall.args[0]).to.equal(
+      'Metadata from retrieved packages is meant for your reference only, not development.'
+    );
+  });
+
   it('should pass along multiple packagenames', async () => {
     const manifest = 'package.xml';
     const packagenames = ['package1', 'package2'];