Merge branch 'trunk' into bb8-12054/fixes-output-option-of-sql-import…

…-command

__tests__/bin/vip-import-validate-files.js

@@ -63,7 +63,7 @@ describe( 'vipImportValidateFilesCmd', () => {
 
 		expect( console.error ).toHaveBeenCalledWith(
 			chalk.red( '✕ Error:' ),
-			'The given path is not a directory, please provide a valid directory path.'
+			'The given path is not a directory. Provide a valid directory path.'
 		);
 	} );
 
@@ -87,7 +87,7 @@ describe( 'vipImportValidateFilesCmd', () => {
 
 		expect( console.error ).toHaveBeenCalledWith(
 			chalk.red( '✕ Error:' ),
-			'Media files directory cannot be empty'
+			'The media files directory cannot be empty.'
 		);
 	} );
 

src/bin/vip-import-media-abort.js

@@ -12,6 +12,8 @@ import { MediaImportProgressTracker } from '../lib/media-import/progress';
 import { mediaImportCheckStatus } from '../lib/media-import/status';
 import { trackEventWithEnv } from '../lib/tracker';
 
+const usage = 'vip import media abort';
+
 const appQuery = `
 	id,
 	name,
@@ -43,57 +45,69 @@ const ABORT_IMPORT_MUTATION = gql`
 	}
 `;
 
+// Command examples
+const examples = [
+	{
+		usage: `vip @example-app.production import media abort`,
+		description:
+			'Abort the media file import that is currently in progress on the production environment of the "example-app" application.',
+	},
+];
+
 command( {
 	appContext: true,
 	appQuery,
 	envContext: true,
 	requiredArgs: 0,
+	usage,
 	requireConfirm: `
 ${ chalk.red.bold(
-	"By running this command, the Media Import running on your App will stop and can't be resumed."
+	'Running this command will stop the currently running media import. The import process cannot be resumed.'
 ) }
-${ chalk.red.bold( 'Are you sure you want to abort this Media Import?' ) }
+${ chalk.red.bold( 'Are you sure you want to abort this media import?' ) }
 `,
-} ).argv( process.argv, async ( arg, { app, env } ) => {
-	const { id: envId, appId } = env;
-	const track = trackEventWithEnv.bind( null, appId, envId );
+} )
+	.examples( examples )
+	.argv( process.argv, async ( arg, { app, env } ) => {
+		const { id: envId, appId } = env;
+		const track = trackEventWithEnv.bind( null, appId, envId );
 
-	if ( ! isSupportedApp( app ) ) {
-		await track( 'import_media_command_error', { errorType: 'unsupported-app' } );
-		exit.withError(
-			'The type of application you specified does not currently support Media imports.'
-		);
-	}
-	const api = API();
+		if ( ! isSupportedApp( app ) ) {
+			await track( 'import_media_command_error', { errorType: 'unsupported-app' } );
+			exit.withError(
+				'The type of application you specified does not currently support media file imports.'
+			);
+		}
+		const api = API();
 
-	await track( 'import_media_abort_execute' );
+		await track( 'import_media_abort_execute' );
 
-	const progressTracker = new MediaImportProgressTracker( [] );
-	progressTracker.prefix = `
+		const progressTracker = new MediaImportProgressTracker( [] );
+		progressTracker.prefix = `
 =============================================================
-Aborting the Media Import running on your App
+Aborting this media import.
 `;
 
-	try {
-		await api.mutate( {
-			mutation: ABORT_IMPORT_MUTATION,
-			variables: {
-				input: {
-					applicationId: app.id,
-					environmentId: env.id,
+		try {
+			await api.mutate( {
+				mutation: ABORT_IMPORT_MUTATION,
+				variables: {
+					input: {
+						applicationId: app.id,
+						environmentId: env.id,
+					},
 				},
-			},
-		} );
-		await mediaImportCheckStatus( { app, env, progressTracker } );
-	} catch ( error ) {
-		if ( error.graphQLErrors ) {
-			for ( const err of error.graphQLErrors ) {
-				console.log( chalk.red( 'Error:' ), err.message );
+			} );
+			await mediaImportCheckStatus( { app, env, progressTracker } );
+		} catch ( error ) {
+			if ( error.graphQLErrors ) {
+				for ( const err of error.graphQLErrors ) {
+					console.log( chalk.red( 'Error:' ), err.message );
+				}
+				return;
 			}
-			return;
+			await track( 'import_media_abort_execute_error', {
+				error: `Error: ${ error.message }`,
+			} );
 		}
-		await track( 'import_media_abort_execute_error', {
-			error: `Error: ${ error.message }`,
-		} );
-	}
-} );
+	} );

src/bin/vip-import-media-status.js

@@ -23,26 +23,46 @@ const appQuery = `
 	}
 `;
 
+const usage = 'vip import media status';
+
+// Command examples
+const examples = [
+	{
+		usage: 'vip @example-app.production import media status',
+		description:
+			'Check the status of the most recent media import.\n' +
+			'       * If the import is still in progress, the command will poll until the import is complete.\n' +
+			'       * If the import is already complete, the command will download an error log for the most recent import.',
+	},
+	{
+		usage:
+			'vip @example-app.production import media status --saveErrorLog --exportFileErrorsToJson',
+		description:
+			'Check the status of the most recent media import and automatically download the error log in JSON format.',
+	},
+];
 command( {
 	appContext: true,
 	appQuery,
 	envContext: true,
 	requiredArgs: 0,
+	usage,
 } )
+	.option( 'exportFileErrorsToJson', 'Format an error log in JSON. Default is TXT.' )
 	.option(
-		'exportFileErrorsToJson',
-		'Export any file errors encountered to a JSON file instead of a plain text file',
-		false
+		'saveErrorLog',
+		'Skip the confirmation prompt and download an error log automatically.',
+		'prompt'
 	)
-	.option( 'saveErrorLog', 'Download file-error logs without prompting', 'prompt' )
+	.examples( examples )
 	.argv( process.argv, async ( arg, { app, env, exportFileErrorsToJson, saveErrorLog } ) => {
 		const { id: envId, appId } = env;
 		const track = trackEventWithEnv.bind( null, appId, envId );
 
 		if ( ! isSupportedApp( app ) ) {
 			await track( 'import_media_command_error', { errorType: 'unsupported-app' } );
 			exit.withError(
-				'The type of application you specified does not currently support this feature'
+				'The type of application you specified does not currently support this feature.'
 			);
 		}
 

src/bin/vip-import-media.js

@@ -42,24 +42,33 @@ const START_IMPORT_MUTATION = gql`
 	}
 `;
 
+const usage = 'vip import media';
+
 const debug = debugLib( 'vip:vip-import-media' );
 
 // Command examples for the `vip import media` help prompt
 const examples = [
 	{
-		usage: 'vip import media @mysite.production https://<path_to_publicly_accessible_archive>',
-		description: 'Start a media import with the contents of the archive file in the URL',
+		usage: 'vip @example-app.production import media https://example.com/uploads.tar.gz',
+		description:
+			'Import the archived file "uploads.tar.gz" from a publicly accessible URL to a production environment.',
 	},
-	// `media status` subcommand
+	// Format error logs
 	{
-		usage: 'vip import media status @mysite.production',
+		usage:
+			'vip @example-app.production import media https://example.com/uploads.tar.gz --overwriteExistingFiles --exportFileErrorsToJson',
 		description:
-			'Check the status of the most recent import. If an import is running, this will poll until it is complete.',
+			'Overwrite existing files with the imported files if they have the same file path and name, and format the error log for the import in JSON.',
+	},
+	// `media status` subcommand
+	{
+		usage: 'vip @example-app.production import media status',
+		description: 'Check the status of the most recent media import.',
 	},
 	// `media abort` subcommand
 	{
-		usage: 'vip import media abort @mysite.production',
-		description: 'Abort an ongoing import',
+		usage: 'vip @example-app.production import media abort',
+		description: 'Abort the currently running media import.',
 	},
 ];
 
@@ -79,6 +88,7 @@ command( {
 	envContext: true,
 	module: 'import-media',
 	requiredArgs: 1,
+	usage,
 	requireConfirm: `
 ${ chalk.red.bold(
 	"NOTE: If the provided archive's directory structure contains an `uploads/` directory,"
@@ -88,19 +98,25 @@ ${ chalk.red.bold(
 ) }
 ${ chalk.red.bold( 'If no `uploads/` directory is found, all files will be imported, as is.' ) }
 
-Are you sure you want to import the contents of the url?
+Are you sure you want to import the contents of the URL?
 `,
 } )
-	.command( 'status', 'Check the status of the latest Media Import' )
-	.command( 'abort', 'Abort the Media Import running for your App' )
+	.command(
+		'status',
+		'Check the status of a currently running media import or retrieve an error log of the most recent media import.'
+	)
+	.command( 'abort', 'Abort the media import currently in progress.' )
+	.option( 'exportFileErrorsToJson', 'Format the error log in JSON. Default is TXT.' )
+	.option(
+		'saveErrorLog',
+		'Skip the confirmation prompt and download an error log for the import automatically.'
+	)
 	.option(
-		'exportFileErrorsToJson',
-		'Export any file errors encountered to a JSON file instead of a plain text file',
+		'overwriteExistingFiles',
+		'Overwrite existing files with the imported files if they have the same path and file name.',
 		false
 	)
-	.option( 'saveErrorLog', 'Download file-error logs without prompting' )
-	.option( 'overwriteExistingFiles', 'Overwrite any existing files', false )
-	.option( 'importIntermediateImages', 'Import intermediate image files', false )
+	.option( 'importIntermediateImages', 'Include intermediate image files in the import.', false )
 	.examples( examples )
 	.argv( process.argv, async ( args, opts ) => {
 		const {
@@ -118,7 +134,7 @@ Are you sure you want to import the contents of the url?
 				chalk.red( `
 Error:
 	Invalid URL provided: ${ url }
-	Please make sure that it is a publicly accessible web URL containing an archive of the media files to import` )
+	Please make sure that it is a publicly accessible web URL containing an archive of the media files to import.` )
 			);
 			return;
 		}

src/bin/vip-import-sql-status.js

@@ -25,34 +25,49 @@ environments{
 }
 `;
 
+const usage = 'vip import sql status';
+
+// Command examples
+const examples = [
+	{
+		usage: 'vip @example-app.develop import sql status',
+		description:
+			'Check the status of the most recent SQL database import to the develop environment of the "example-app" application.\n' +
+			'       * If the import is still in progress, the command will poll until the import is complete.',
+	},
+];
+
 command( {
 	appContext: true,
 	appQuery,
 	envContext: true,
 	requiredArgs: 0,
-} ).argv( process.argv, async ( arg, { app, env } ) => {
-	const { id: envId, appId } = env;
-	const track = trackEventWithEnv.bind( null, appId, envId );
-
-	if ( ! isSupportedApp( app ) ) {
-		await track( 'import_sql_command_error', { errorType: 'unsupported-app' } );
-		exit.withError(
-			'The type of application you specified does not currently support SQL imports.'
-		);
-	}
+	usage,
+} )
+	.examples( examples )
+	.argv( process.argv, async ( arg, { app, env } ) => {
+		const { id: envId, appId } = env;
+		const track = trackEventWithEnv.bind( null, appId, envId );
+
+		if ( ! isSupportedApp( app ) ) {
+			await track( 'import_sql_command_error', { errorType: 'unsupported-app' } );
+			exit.withError(
+				'The type of application you specified does not currently support SQL imports.'
+			);
+		}
 
-	await track( 'import_sql_check_status_command_execute' );
+		await track( 'import_sql_check_status_command_execute' );
 
-	const progressTracker = new ProgressTracker( [] );
-	progressTracker.prefix = `
+		const progressTracker = new ProgressTracker( [] );
+		progressTracker.prefix = `
 =============================================================
 Checking the SQL import status for your environment...
 `;
 
-	await importSqlCheckStatus( {
-		app,
-		env,
-		progressTracker,
-		shouldReturnMissingJobImmediately: true,
+		await importSqlCheckStatus( {
+			app,
+			env,
+			progressTracker,
+			shouldReturnMissingJobImmediately: true,
+		} );
 	} );
-} );