Merge branch 'main' of github.com:vercel/vercel into update/next-option-description

TooTallNate · TooTallNate · commit d7c2e75ddc1b · 2024-11-04T09:36:22.000-08:00
diff --git a/.changeset/chilly-comics-play.md b/.changeset/chilly-comics-play.md
@@ -0,0 +1,5 @@
+---
+'vercel': patch
+---
+
+Don't print empty "Options" section in `--help` output (after filtering)
diff --git a/.changeset/flat-olives-applaud.md b/.changeset/flat-olives-applaud.md
@@ -0,0 +1,5 @@
+---
+'vercel': minor
+---
+
+Migrate `vercel promote` subcommands to their own command specifications
diff --git a/.changeset/tall-coins-sip.md b/.changeset/tall-coins-sip.md
@@ -0,0 +1,5 @@
+---
+'vercel': patch
+---
+
+Consistent help output for `--limit` option
diff --git a/.changeset/twenty-drinks-own.md b/.changeset/twenty-drinks-own.md
@@ -0,0 +1,5 @@
+---
+'vercel': minor
+---
+
+Migrate `vercel target` subcommands to their own command specifications
diff --git a/.changeset/witty-parents-buy.md b/.changeset/witty-parents-buy.md
@@ -0,0 +1,2 @@
+---
+---
diff --git a/README.md b/README.md
@@ -33,7 +33,7 @@ For details on how to use Vercel, check out our [documentation](https://vercel.c
 
 This project uses [pnpm](https://pnpm.io/) to install dependencies and run scripts.
 
-You can use the `dev` script to run local changes as if you were invoking Vercel CLI. For example, `vercel deploy --cwd=/path/to/project` could be run with local changes with `pnpm dev deploy --cwd=/path/to/project`.
+You can use the `vercel` script to run local changes as if you were invoking Vercel CLI. For example, `vercel deploy --cwd=/path/to/project` could be run with local changes with `pnpm vercel deploy --cwd=/path/to/project`.
 
 When contributing to this repository, please first discuss the change you wish to make via [GitHub Discussions](https://github.com/vercel/vercel/discussions/new) with the owners of this repository before submitting a Pull Request.
 
diff --git a/packages/cli/src/commands/alias/command.ts b/packages/cli/src/commands/alias/command.ts
@@ -25,15 +25,7 @@ export const listSubcommand = {
   aliases: ['ls'],
   description: 'Show all aliases',
   arguments: [],
-  options: [
-    {
-      ...limitOption,
-      description:
-        'Number of results to return per page (default: 20, max: 100)',
-      argument: 'NUMBER',
-    },
-    nextOption,
-  ],
+  options: [limitOption, nextOption],
   examples: [],
 } as const;
 
diff --git a/packages/cli/src/commands/certs/command.ts b/packages/cli/src/commands/certs/command.ts
@@ -77,15 +77,7 @@ export const listSubcommand = {
   aliases: ['list'],
   description: 'Show all available certificates',
   arguments: [],
-  options: [
-    {
-      ...limitOption,
-      description:
-        'Number of results to return per page (default: 20, max: 100)',
-      argument: 'VALUE',
-    },
-    nextOption,
-  ],
+  options: [limitOption, nextOption],
   examples: [
     {
       name: 'Paginate results, where `1584722256178` is the time in milliseconds since the UNIX epoch.',
diff --git a/packages/cli/src/commands/deploy/command.ts b/packages/cli/src/commands/deploy/command.ts
@@ -135,11 +135,7 @@ export const deployCommand = {
       deprecated: false,
       description: 'Specify the target deployment environment',
     },
-    {
-      ...confirmOption,
-      deprecated: true,
-      description: 'Use default options to skip all prompts',
-    },
+    confirmOption,
   ],
   examples: [
     {
diff --git a/packages/cli/src/commands/dev/command.ts b/packages/cli/src/commands/dev/command.ts
@@ -22,7 +22,7 @@ export const devCommand = {
     },
     yesOption,
     { name: 'port', shorthand: 'p', type: String, deprecated: true },
-    { ...confirmOption, deprecated: true },
+    confirmOption,
   ],
   examples: [
     {
diff --git a/packages/cli/src/commands/dns/command.ts b/packages/cli/src/commands/dns/command.ts
@@ -30,15 +30,7 @@ export const listSubcommand = {
       required: true,
     },
   ],
-  options: [
-    {
-      ...limitOption,
-      description:
-        'Number of results to return per page (default: 20, max: 100)',
-      argument: 'NUMBER',
-    },
-    nextOption,
-  ],
+  options: [limitOption, nextOption],
   examples: [],
 } as const;
 
diff --git a/packages/cli/src/commands/domains/command.ts b/packages/cli/src/commands/domains/command.ts
@@ -113,12 +113,7 @@ export const domainsCommand = {
       ...yesOption,
       description: 'Skip the confirmation prompt when removing a domain',
     },
-    {
-      ...limitOption,
-      description:
-        'Number of results to return per page (default: 20, max: 100)',
-      argument: 'NUMBER',
-    },
+    limitOption,
     nextOption,
     {
       ...forceOption,
diff --git a/packages/cli/src/commands/git/command.ts b/packages/cli/src/commands/git/command.ts
@@ -30,7 +30,7 @@ export const gitCommand = {
       examples: [],
     },
   ],
-  options: [yesOption, { ...confirmOption, deprecated: true }],
+  options: [yesOption, confirmOption],
   examples: [
     {
       name: 'Connect your Vercel Project to your Git repository defined in your local .git config',
diff --git a/packages/cli/src/commands/help.ts b/packages/cli/src/commands/help.ts
@@ -140,15 +140,15 @@ export function buildCommandOptionLines(
   options: BuildHelpOutputOptions,
   sectionTitle: String
 ) {
-  if (commandOptions.length === 0) {
-    return null;
-  }
-
   // Filter out deprecated and intentionally undocumented options
   const filteredCommandOptions = commandOptions.filter(
     option => !option.deprecated && option.description !== undefined
   );
 
+  if (filteredCommandOptions.length === 0) {
+    return null;
+  }
+
   // Sort command options alphabetically
   filteredCommandOptions.sort((a, b) =>
     a.name < b.name ? -1 : a.name > b.name ? 1 : 0
diff --git a/packages/cli/src/commands/link/command.ts b/packages/cli/src/commands/link/command.ts
@@ -27,7 +27,7 @@ export const linkCommand = {
       description:
         'Skip questions when setting up new project using default scope and settings',
     },
-    { ...confirmOption, deprecated: true },
+    confirmOption,
   ],
   examples: [
     {
diff --git a/packages/cli/src/commands/list/command.ts b/packages/cli/src/commands/list/command.ts
@@ -42,7 +42,7 @@ export const listCommand = {
     // this can be deprecated someday
     { name: 'prod', shorthand: null, type: Boolean, deprecated: false },
     yesOption,
-    { ...confirmOption, deprecated: true },
+    confirmOption,
   ],
   examples: [
     {
diff --git a/packages/cli/src/commands/promote/command.ts b/packages/cli/src/commands/promote/command.ts
@@ -1,31 +1,45 @@
 import { packageName } from '../../util/pkg-name';
 import { yesOption } from '../../util/arg-common';
 
-export const promoteCommand = {
-  name: 'promote',
+export const statusSubcommand = {
+  name: 'status',
   aliases: [],
-  description: 'Promote an existing deployment to current.',
+  description: 'Show the status of any current pending promotions',
   arguments: [
     {
-      name: 'url|deploymentId',
-      required: true,
+      name: 'project',
+      required: false,
     },
   ],
-  subcommands: [
+  options: [
+    {
+      ...yesOption,
+      description: 'Skip the confirmation prompt when linking a Project',
+    },
+  ],
+  examples: [
     {
-      name: 'status',
-      aliases: [],
-      description: 'Show the status of any current pending promotions',
-      arguments: [
-        {
-          name: 'project',
-          required: false,
-        },
+      name: 'Show the status of any current pending promotions',
+      value: [
+        `${packageName} promote status`,
+        `${packageName} promote status <project>`,
+        `${packageName} promote status --timeout 30s`,
       ],
-      options: [],
-      examples: [],
     },
   ],
+} as const;
+
+export const promoteCommand = {
+  name: 'promote',
+  aliases: [],
+  description: 'Promote an existing Deployment to current',
+  arguments: [
+    {
+      name: 'url|deploymentId',
+      required: true,
+    },
+  ],
+  subcommands: [statusSubcommand],
   options: [
     {
       name: 'timeout',
@@ -35,21 +49,15 @@ export const promoteCommand = {
       type: String,
       deprecated: false,
     },
-    yesOption,
-  ],
-  examples: [
     {
-      name: 'Show the status of any current pending promotions',
-      value: [
-        `${packageName} promote`,
-        `${packageName} promote status`,
-        `${packageName} promote status <project>`,
-        `${packageName} promote status --timeout 30s`,
-      ],
+      ...yesOption,
+      description: 'Skip the confirmation prompt when linking a Project',
     },
+  ],
+  examples: [
     {
-      name: 'Promote a deployment using id or url',
-      value: `${packageName} promote <deployment id/url>`,
+      name: 'Promote a Deployment using ID or URL',
+      value: `${packageName} promote <deployment id|url>`,
     },
   ],
 } as const;
diff --git a/packages/cli/src/commands/promote/index.ts b/packages/cli/src/commands/promote/index.ts
@@ -1,32 +1,29 @@
-import type Client from '../../util/client';
+import ms from 'ms';
 import { parseArguments } from '../../util/get-args';
 import getProjectByCwdOrLink from '../../util/projects/get-project-by-cwd-or-link';
 import handleError from '../../util/handle-error';
 import { isErrnoException } from '@vercel/error-utils';
-import ms from 'ms';
 import requestPromote from './request-promote';
 import promoteStatus from './status';
-import { promoteCommand } from './command';
+import { promoteCommand, statusSubcommand } from './command';
 import { help } from '../help';
 import { getFlagsSpecification } from '../../util/get-flags-specification';
 import { PromoteTelemetryClient } from '../../util/telemetry/commands/promote';
 import output from '../../output-manager';
+import type Client from '../../util/client';
 
 /**
  * `vc promote` command
  * @param {Client} client
  * @returns {Promise<number>} Resolves an exit code; 0 on success
  */
 export default async (client: Client): Promise<number> => {
-  let parsedArgs = null;
-
+  let parsedArgs;
   const flagsSpecification = getFlagsSpecification(promoteCommand.options);
-
-  // Parse CLI args
   try {
     parsedArgs = parseArguments(client.argv.slice(2), flagsSpecification);
-  } catch (error) {
-    handleError(error);
+  } catch (err) {
+    handleError(err);
     return 1;
   }
 
@@ -36,7 +33,9 @@ export default async (client: Client): Promise<number> => {
     },
   });
 
-  if (parsedArgs.flags['--help']) {
+  const needHelp = parsedArgs.flags['--help'];
+
+  if (!parsedArgs.args[1] && needHelp) {
     telemetry.trackCliFlagHelp('promote');
     output.print(help(promoteCommand, { columns: client.stderr.columns }));
     return 2;
@@ -58,6 +57,16 @@ export default async (client: Client): Promise<number> => {
 
   try {
     if (actionOrDeployId === 'status') {
+      if (needHelp) {
+        telemetry.trackCliFlagHelp('promote', 'status');
+        output.print(
+          help(statusSubcommand, {
+            columns: client.stderr.columns,
+            parent: promoteCommand,
+          })
+        );
+        return 2;
+      }
       telemetry.trackCliSubcommandStatus();
       const project = await getProjectByCwdOrLink({
         autoConfirm: Boolean(parsedArgs.flags['--yes']),
diff --git a/packages/cli/src/commands/target/command.ts b/packages/cli/src/commands/target/command.ts
@@ -1,25 +1,25 @@
 import { packageName } from '../../util/pkg-name';
 
-export const targetCommand = {
-  name: 'target',
-  aliases: ['targets'],
-  description: 'Manage your Vercel Project\'s "targets" (custom environments).',
+export const listSubcommand = {
+  name: 'list',
+  aliases: ['ls'],
+  description: 'List targets defined for the current Project',
   arguments: [],
-  subcommands: [
-    {
-      name: 'ls',
-      aliases: ['list'],
-      description: 'Show all targets in the current project',
-      arguments: [],
-      options: [],
-      examples: [],
-    },
-  ],
   options: [],
   examples: [
     {
-      name: 'List all targets for the current project',
+      name: 'List all targets for the current Project',
       value: `${packageName} target ls my-project`,
     },
   ],
 } as const;
+
+export const targetCommand = {
+  name: 'target',
+  aliases: ['targets'],
+  description: 'Manage your Vercel Project\'s "targets" (custom environments).',
+  arguments: [],
+  subcommands: [listSubcommand],
+  options: [],
+  examples: [],
+} as const;
diff --git a/packages/cli/src/commands/target/index.ts b/packages/cli/src/commands/target/index.ts
diff --git a/packages/cli/src/commands/target/list.ts b/packages/cli/src/commands/target/list.ts
diff --git a/packages/cli/src/util/arg-common.ts b/packages/cli/src/util/arg-common.ts
diff --git a/packages/cli/src/util/telemetry/commands/target/index.ts b/packages/cli/src/util/telemetry/commands/target/index.ts
diff --git a/packages/cli/test/unit/commands/__snapshots__/help.test.ts.snap b/packages/cli/test/unit/commands/__snapshots__/help.test.ts.snap
diff --git a/packages/cli/test/unit/commands/help.test.ts b/packages/cli/test/unit/commands/help.test.ts
diff --git a/packages/cli/test/unit/commands/promote/index.test.ts b/packages/cli/test/unit/commands/promote/index.test.ts
diff --git a/packages/cli/test/unit/commands/promote/status.test.ts b/packages/cli/test/unit/commands/promote/status.test.ts
diff --git a/packages/cli/test/unit/commands/target/list.test.ts b/packages/cli/test/unit/commands/target/list.test.ts

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'vercel': patch
 +---
++
 +Don't print empty "Options" section in `--help` output (after filtering)
Original file line number	Diff line number	Diff line change
`@@ -22,7 +22,7 @@ export const devCommand = {`
`22`	`22`	`},`
`23`	`23`	`yesOption,`
`24`	`24`	`{ name: 'port', shorthand: 'p', type: String, deprecated: true },`
`25`		`- { ...confirmOption, deprecated: true },`
	`25`	`+ confirmOption,`
`26`	`26`	`],`
`27`	`27`	`examples: [`
`28`	`28`	`{`