@caweb/cli 1.0.5 → 1.2.0

package/README.md

@@ -1,45 +1,55 @@
 # caweb-cli
-`caweb-cli` utilizes [wp-env](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/) in the background; to rapidly set up a local WordPress environment, fully configured for the [CAWebPublishing Service](https://caweb.cdt.ca.gov/). The cli will automatically generate the necessary [.wp-env.json](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/#wp-env-json) file, to override or add additional configuration options use the [.wp-env.override.json](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/#wp-env-override-json) file.
+`caweb-cli` is a tool which rapidly sets up a local WordPress environment fully configured for the [CAWebPublishing Service](https://caweb.cdt.ca.gov/), allows for the creation of Gutenberg blocks with the CAWebPublishing template configurations, and much more. The cli will automatically generate the necessary [.wp-env.json](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/#wp-env-json) file, to override or add additional configuration options use the [.wp-env.override.json](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/#wp-env-override-json) file.
 
-## Additional Features
-- Downloads and configures the [CAWeb Theme](https://github.com/CA-cODE-Works/CAWeb)  
-- Downloads and configures the [Divi Theme](https://www.elegantthemes.com/gallery/divi/) (*requires valid ElegantThemes Username and API Key*)  
-- Adds phpMyAdmin Service for both WordPress environments. (Username: <strong>bold</strong> , Password: <strong>password</strong>)  
--- phpMyAdmin development site starts at http://localhost:8080  
--- phpMyAdmin test site started at http://localhost:9090
+*`caweb-cli` is largely inspired by WordPress Packages major thanks to the whole WordPress team and community!*  
+The following WordPress packages are used:  
+[wp-env](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/)  
+[create-block](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/)
+
+## Prerequisites
+- Latest version of [Docker Desktop](https://www.docker.com/products/docker-desktop), which includes [Compose v2}(https://docs.docker.com/compose/migrate/), is installed.
+  - <strong>For Debian-Based Linux distributions:</strong> <code>docker-compose</code> may need to be installed with: <code>sudo apt-get install docker-compose</code>.
+  - <strong>For Windows users:</strong> [WSL should be set to version 2 for Windows Docker Desktop compatibility](https://docs.docker.com/desktop/windows/wsl/).
+- git is installed.
 
+## Additional Features
+- Downloads and configures the [CAWeb Theme](https://github.com/CAWebPublishing/CAWeb)
+- Downloads approved plugins utilized by the CAWebPublishing Service  
+- Downloads and configures the [Divi Theme](https://www.elegantthemes.com/gallery/divi/) and [Divi Builder Plugin](https://www.elegantthemes.com/gallery/divi/) (*requires valid ElegantThemes Username and API Key*)  
+- Adds phpMyAdmin Service for both WordPress environments. (Username: <strong>root</strong> , Password: <strong>password</strong>)  
+  - phpMyAdmin development site starts at http://localhost:8080  
+  - phpMyAdmin test site started at http://localhost:9090
+- Uses CAWebPublishing [External Project Template Configuration](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/packages-create-block-external-template/) when creating Gutenberg Blocks, see configurations [here](https://github.com/CAWebPublishing/cli/lib/template)
 - Adds config.yml to both cli containers 
 <pre>
 path: /var/www/html
 apache_modules:
   - mod_rewrite
 </pre>
+.
+
 ## Command Reference
 ### `caweb start`  
 Generates the required wp-env.json, starts the WordPress environment, downloads any CAWebPublishing sources and approved plugins.  
 <pre>
-caweb start
+caweb start [options]
+
+Starts two CAWebPublishing WordPress instances
+development on port 8888 (​http://localhost:8888​) (override with WP_ENV_PORT)
+tests on port 8889 (​http://localhost:8889​) (override with WP_ENV_TESTS_PORT).
+After first install, use the '--update' flag to download updates to mapped sources and to re-apply CAWeb configuration options.
 
 Options:
-      --debug      Enable debug output.               [boolean] [default: false]
-      --update     Download source updates and apply WordPress configuration.
-                                                      [boolean] [default: false]
-      --xdebug     Enables Xdebug. If not passed, Xdebug is turned off. If no
-                   modes are set, uses "debug". You may set multiple Xdebug
-                   modes by passing them in a comma-separated list:
-                   `--xdebug=develop,coverage`. See
-                   https://xdebug.org/docs/all_settings#mode for information
-                   about Xdebug modes.                                  [string]
-      --scripts    Execute any configured lifecycle scripts.
-                                                       [boolean] [default: true]
-      --bare       True if excluding any downloads from CAWeb, use this if you
-                   want to use a local version of the CAWeb Theme,
-                   Configurations will still be applied.
-                                                      [boolean] [default: false]
-  -m, --multisite  True if converting to multisite.   [boolean] [default: false]
-      --subdomain  If passed, the network will use subdomains, instead of
-                   subdirectories. Doesn't work with 'localhost', make sure to
-                   set Port to 80.                    [boolean] [default: false]
+  --bare           True if excluding any downloads from CAWeb, use this if you want to use a local version of the CAWeb Theme, Configurations will still be applied. (default: false)
+  -h, --help       display help for command
+  -m, --multisite  True if converting to multisite. (default: false)
+  -p, --plugin     True if root directory is a plugin. (default: false)
+  --scripts        Execute any configured lifecycle scripts. (default: true)
+  --subdomain      If passed, the network will use subdomains, instead of subdirectories. Doesn't work with 'localhost', make sure to set Port to 80. (default: false)
+  -t, --theme      True if root directory is a theme. (default: false)
+  --update         Download source updates and apply WordPress configuration. (default: false)
+  --xdebug <mode>  Enables Xdebug. If not passed, Xdebug is turned off. If no modes are set, uses "debug". You may set multiple Xdebug modes by passing them in a comma-separated list:
+                   `--xdebug=develop,coverage`. See https://xdebug.org/docs/all_settings#mode for information about Xdebug modes.
 </pre>
 ### `caweb stop`  
 <pre>
@@ -148,3 +158,28 @@ Positionals:
 Options:
   --debug    Enable debug output.                     [boolean] [default: false]
 </pre>
+
+### `caweb create-block [options] <slug>`  
+<pre>
+caweb create-block [options] <slug>
+
+Scaffold for WordPress plugin to register CA.gov Design System Block.
+
+Arguments:
+  slug           Plugin slug to use.
+
+Options:
+  -h, --help     display help for command
+</pre>
+### `caweb update-block [options] <slug>`  
+<pre>
+caweb update-block [options] <slug>
+
+Updates a CA.gov Design System Block.
+
+Arguments:
+  slug           Plugin slug to update.
+
+Options:
+  -h, --help     display help for command
+</pre>

package/bin/caweb

@@ -1,20 +1,6 @@
 #!/usr/bin/env node
-'use strict';
 
-// Remove 'node' and the name of the script from the arguments.
-let command = process.argv.slice( 2 );
-// Default to help text when they aren't running any commands.
-if ( ! command.length ) {
-	command = [ '--help' ];
-}
-
-// Rather than just executing the current CLI we will attempt to find a local version
-// and execute that one instead. This prevents users from accidentally using the
-// global CLI when a potentially different local version is expected.
-const localPath = require.resolve( '@caweb/cli/lib/cli.js', {
-	paths: [ process.cwd(), __dirname ],
-} );
-const cli = require( localPath )();
+import cli from '../lib/cli.js';
 
-// Now we can execute the CLI with the given command.
-cli.parse( command );
+// Default to help text when they aren't running any commands.
+cli().parse( ! process.argv.length ? [ '--help' ] : process.argv );

package/lib/admin.js

@@ -0,0 +1,40 @@
+/**
+ * External dependencies
+ */
+import path from 'node:path';
+import fs from 'fs-extra';
+
+import { CAWEB_OPTIONS, DIVI_OPTIONS } from './options.js';
+
+/**
+ * Generates the OVERRIDES.MD
+ * 
+ */
+export default async function generateOverridesMD() {
+
+	let output = [
+		'## [.wp-env.override.json](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/#wp-env-override-json)',
+		'Any fields here will take precedence over .wp-env.json.',
+		'## <ins>Special Config Values</ins>',
+	];
+
+	// Generate CAWeb Options overrides.
+	output.push('### <ins>CAWeb Options</ins>');
+	for (const [key, option] of Object.entries(CAWEB_OPTIONS)) {
+		output.push(`\`${key}\` - Updates CAWeb ${option.label}  `);
+	}
+	  
+	// Generate Divi Options overrides.
+	output.push('### <ins>Divi Options</ins>');
+	for (const [group, options] of Object.entries(DIVI_OPTIONS)) {
+		for (const [key, option] of Object.entries(options)) {
+			output.push(`\`${key}\` - Updates CAWeb ${option.label}  `);
+		}
+	}
+
+	await fs.writeFileSync(
+		path.join(process.cwd(), 'docs', 'OVERRIDES.MD'),
+		output.join('\n')
+	);
+
+};

package/lib/caweb.js

@@ -1,29 +1,30 @@
-'use strict';
 /**
  * External dependencies
  */
-const retry = require( '@wordpress/env/lib/retry' );
+import retry from '@wordpress/env/lib/retry.js';
 
 /**
  * Internal dependencies
  */
-const { CAWEB_OPTIONS } = require('./options');
-const { runDockerCmds } = require('./docker');
-const { isMultisite } = require('./wordpress');
-const { configureDivi } = require('./divi');
+import { CAWEB_OPTIONS } from'./options.js';
+import { runCLICmds } from'./utils.js';
+import { isMultisite } from'./wordpress.js';
+import { configureDivi } from'./divi.js';
 
 /**
  * Activates the CAWeb Theme for the WordPress Environment if it's installed.
  * 
  * @param {string}		environment   Which environment to activate the theme on.
  * @param {WPConfig} 	config	      The wp-env config object.
+ * @param {Object}   	spinner A CLI spinner which indicates progress.
  */
 async function activateCAWeb(
 	environment,
-	config
+	config,
+	spinner
 ){
 
-	const isMulti = await isMultisite( environment, config );
+	const isMulti = await isMultisite( environment, config , spinner);
 
 	let cmds = ['wp theme is-installed CAWeb'];
 
@@ -33,10 +34,11 @@ async function activateCAWeb(
 		cmds.push( 'wp theme activate CAWeb' );
 	}
 
-	return await runDockerCmds(
+	return await runCLICmds(
 		environment,
 		cmds,
-		config
+		config,
+		spinner
 	);
 
 }
@@ -56,8 +58,7 @@ async function configureCAWeb( environment, config, spinner ) {
 	const isThemeActivated = await activateCAWeb( environment, config );
 
 	const {
-		DESIGN_SYSTEM_ENABLED,
-		WP_PERMALINK
+		DESIGN_SYSTEM_ENABLED
 	} = config.env[ environment ].config
 
 	// if our theme is active.
@@ -87,10 +88,11 @@ async function configureCAWeb( environment, config, spinner ) {
 		}
 		
 		// Execute theme option commands.
-		await runDockerCmds(
+		await runCLICmds(
 			environment,
 			themeOptions,
-			config
+			config,
+			spinner
 		);
 
 		// Make Divi WordPress Configurations.
@@ -106,20 +108,21 @@ async function configureCAWeb( environment, config, spinner ) {
 		
 	// Activate Design System plugin
 	if( undefined !== DESIGN_SYSTEM_ENABLED && DESIGN_SYSTEM_ENABLED ){
-		await runDockerCmds(
+		await runCLICmds(
 			environment,
 			[
 				'wp plugin is-installed design-system-wordpress', 
 				'wp plugin activate design-system-wordpress'
 			],
-			config
+			config,
+			spinner
 		)
 	}
 	
 	
 }
 
-module.exports = {
+export {
 	activateCAWeb,
 	configureCAWeb,
 };

package/lib/cli.js

@@ -1,153 +1,235 @@
-'use strict';
 /**
  * External dependencies
  */
-const wpenv_cli = require('@wordpress/env/lib/cli');
+//const wpenv_cli = require('@wordpress/env/lib/cli');
 
-const chalk = require( 'chalk' );
-const ora = require( 'ora' );
-let yargs = require( 'yargs' );
-const terminalLink = require( 'terminal-link' );
-const { execSync } = require( 'child_process' );
+import path from 'node:path';
+import chalk from 'chalk';
+import parseXdebugMode from '@wordpress/env/lib/parse-xdebug-mode.js';
+import fs from 'fs-extra';
+import terminalLink from  'terminal-link';
+import { Command, Argument, Option } from 'commander';
 
 /**
  * Internal dependencies
  */
-const pkg = require( '../package.json' );
-const env = require( './commands' );
-const parseXdebugMode = require( '@wordpress/env/lib/parse-xdebug-mode' );
-
-// Colors.
-const boldWhite = chalk.bold.white;
-const wpPrimary = boldWhite.bgHex( '#00669b' );
-const wpGreen = boldWhite.bgHex( '#4ab866' );
-const wpRed = boldWhite.bgHex( '#d94f4f' );
-const wpYellow = boldWhite.bgHex( '#f0b849' );
-
-// Spinner.
-const withSpinner =
-	( command ) =>
-	( ...args ) => {
-		const spinner = ora().start();
-		args[ 0 ].spinner = spinner;
-		let time = process.hrtime();
-		return command( ...args ).then(
-			( message ) => {
-				time = process.hrtime( time );
-				spinner.succeed(
-					`${ message || spinner.text } (in ${ time[ 0 ] }s ${ (
-						time[ 1 ] / 1e6
-					).toFixed( 0 ) }ms)`
-				);
-				process.exit( 0 );
-			},
-			( error ) => {
-				if( error ){
-					// Error is an unknown error. That means there was a bug in our code.
-					spinner.fail(
-						typeof error === 'string' ? error : error.message
-					);
-					// Disable reason: Using console.error() means we get a stack trace.
-					console.error( error );
-					process.exit( 1 );
-				}else{
-					spinner.fail( 'An unknown error occurred.' );
-					process.exit( 1 );
-				}
-			}
-		);
-	};
-
-module.exports = function cli() {
-	yargs = wpenv_cli();
-
-	// we are overwriting the default wp-env start command with our own.
-	yargs.command(
-		'start',
-		false,
-		( args ) => {
-			args.option( 'update', {
-				type: 'boolean',
-				describe:
-					'Download source updates and apply WordPress configuration.',
-				default: false,
-			} );
-			args.option( 'xdebug', {
-				describe:
-					'Enables Xdebug. If not passed, Xdebug is turned off. If no modes are set, uses "debug". You may set multiple Xdebug modes by passing them in a comma-separated list: `--xdebug=develop,coverage`. See https://xdebug.org/docs/all_settings#mode for information about Xdebug modes.',
-				coerce: parseXdebugMode,
-				type: 'string',
-			} );
-			args.option( 'scripts', {
-				type: 'boolean',
-				describe: 'Execute any configured lifecycle scripts.',
-				default: true,
-			} );
-			args.option( 'bare', {
-				type: 'boolean',
-				describe: 'True if excluding any downloads from CAWeb, use this if you want to use a local version of the CAWeb Theme, Configurations will still be applied.',
-				default: false,
-			} );
-			args.option( 'multisite', {
-				alias: 'm',
-				type: 'boolean',
-				describe: 'True if converting to multisite.',
-				default: false,
-			} );
-			args.option( 'subdomain', {
-				type: 'boolean',
-				describe: "If passed, the network will use subdomains, instead of subdirectories. Doesn't work with 'localhost', make sure to set Port to 80.",
-				default: false,
-			} );
-		},
-		withSpinner( env.start )
-	);
-
-	// Shell Terminal Command.
-	yargs.command(
-		'shell [environment]',
-		'Open shell terminal in WordPress environment.', 
-		(args) => {
-			args.positional( 'environment', {
-				type: 'string',
-				describe: "Which environment to open terminal in.",
-				choices: [ 'development', 'tests' ],
-				default: 'development',
-			} );
-		}, 
-		withSpinner( env.shell )
-	)
-
-	// Update Plugin Command.
-	yargs.command(
-		'update-plugins [environment]',
-		'Updates all plugins in the WordPress environment.', 
-		(args) => {
-			args.positional( 'environment', {
-				type: 'string',
-				describe: "Which environment to update.",
-				choices: [ 'development', 'tests' ],
-				default: 'development',
-			} );
-		}, 
-		withSpinner( env.updatePlugins )
-	)
+import * as env from './commands/index.js';
+import {
+	wpPrimary,
+	wpGreen,
+	wpYellow,
+	wpRed,
+	withSpinner
+} from './spinner.js';
 
-	// Test Command.
-	/*yargs.command(
-		'test [environment]',
-		'Test commands on a WordPress environment', 
-		(args) => {
-			args.positional( 'environment', {
-				type: 'string',
-				describe: "Which environment to test in.",
-				choices: [ 'development', 'tests' ],
-				default: 'development',
-			} );
-			
-		}, 
-		withSpinner( env.test )
-	)*/
+const localPath = path.resolve( path.join(process.cwd(), 'node_modules/@caweb/cli/package.json') )
+const pkg = JSON.parse( await fs.readFile(localPath) );
+const program = new Command();
+
+export default function cli() {
+	const envArg = new Argument('[environment]', 'Which environment to use.')
+		.choices([
+			'development', 
+			'tests', 
+			'all'
+		])
+		.default('development');
+
+	const containerArg = new Argument('<container>', 'The underlying Docker service to run the command on.')
+		.choices([
+			'mysql',
+			'tests-mysql',
+			'wordpress',
+			'tests-wordpress',
+			'cli',
+			'tests-cli',
+		])
+		.default('development');
+
+	program
+		.name(wpPrimary( 'caweb'))
+		.usage( wpYellow( '<command>' ) )
+		.description('Command Line Interface utilized by CAWebPublishing to accomplish several tasks.')
+		.version( pkg.version )
+		.option(
+			'--debug',
+			'Enable debug output.',
+			false
+		)
+		.allowUnknownOption(true)
+		.configureHelp({ 
+			sortSubcommands: true,
+			sortOptions: true,
+			showGlobalOptions: true,
+		})
+		.addHelpCommand(false)
+
+	// Start command.
+	program.command('start')
+		.description(
+			wpGreen(
+				chalk`Starts two CAWebPublishing WordPress instances\ndevelopment on port ${ terminalLink( '8888', 'http://localhost:8888' ) } (override with WP_ENV_PORT)\ntests on port {bold.underline ${ terminalLink( '8889', 'http://localhost:8889' ) }} (override with WP_ENV_TESTS_PORT).\nAfter first install, use the '--update' flag to download updates to mapped sources and to re-apply CAWeb configuration options.`
+			)
+		)
+		.option( 
+			'--update',
+			'Download source updates and apply WordPress configuration.',
+			false
+		)
+		.option( 
+			'--xdebug <mode>',
+			'Enables Xdebug. If not passed, Xdebug is turned off. If no modes are set, uses "debug". You may set multiple Xdebug modes by passing them in a comma-separated list: `--xdebug=develop,coverage`. See https://xdebug.org/docs/all_settings#mode for information about Xdebug modes.',
+		)
+		.option( 
+			'--scripts', 
+			'Execute any configured lifecycle scripts.',
+			true
+		)
+		.option(
+			'--bare',
+			'True if excluding any downloads from CAWeb, use this if you want to use a local version of the CAWeb Theme, Configurations will still be applied.',
+			false
+		)
+		.option(
+			'-p, --plugin',
+			'True if root directory is a plugin.',
+			false
+		)
+		.option(
+			'-t, --theme',
+			'True if root directory is a theme.',
+			false
+		)
+		.option(
+			'-m, --multisite',
+			'True if converting to multisite.',
+			false
+		)
+		.option(
+			'--subdomain',
+			"If passed, the network will use subdomains, instead of subdirectories. Doesn't work with 'localhost', make sure to set Port to 80.",
+			false
+		)
+		.allowUnknownOption(true)
+		.action( withSpinner(env.start) )
+
+	// Destroy Command.
+	program.command('destroy')
+		.description(
+			wpRed(
+				'Deletes docker containers, volumes, and networks associated with the CAWebPublishing instances and removes local files.'
+			)
+		)
+		.option( 
+			'--scripts', 
+			'Execute any configured lifecycle scripts.',
+			true
+		)
+		.allowUnknownOption(true)
+		.action( withSpinner(env.destroy) )
+
+	// Shell Command.
+	program.command('shell')
+		.description('Open shell terminal in WordPress environment.')
+		.addArgument(envArg)
+		.allowUnknownOption(true)
+		.action( withSpinner(env.shell) )
+
+	// Stop Command.
+	program.command('stop')
+		.description(
+			wpRed(
+				'Stops running WordPress for development and tests and frees the ports.'
+			)
+		)
+		.allowUnknownOption(true)
+		.action( withSpinner(env.stop) )
+
+	// Clean Command.
+	program.command('clean')
+		.description(
+			wpYellow( 'Cleans the WordPress databases.' )
+		)
+		.addArgument(envArg)
+		.option( 
+			'--scripts', 
+			'Execute any configured lifecycle scripts.',
+			true
+		)
+		.allowUnknownOption(true)
+		.action( withSpinner(env.clean) )
 	
-	return yargs;
+	// Logs Command.
+	program.command('logs')
+		.description(
+			'Displays PHP and Docker logs for given WordPress environment.'
+		)
+		.addArgument(envArg)
+		.option( 
+			'--no-watch', 
+			'Stops watching for logs in realtime.',
+			true
+		)
+		.allowUnknownOption(true)
+		.action( withSpinner(env.logs) )
+	
+		
+	// Run Command.
+	program.command('run')
+		.description(
+			'Runs an arbitrary command in one of the underlying Docker containers. A double dash can be used to pass arguments to the container without parsing them. This is necessary if you are using an option that is defined below. You can use `bash` to open a shell session and both `composer` and `phpunit` are available in all WordPress and CLI containers. WP-CLI is also available in the CLI containers.'
+		)
+		.addArgument(containerArg)
+		.argument('[command...]', 'The command to run.')
+		.option( 
+			'--env-cwd', 
+			"The command's working directory inside of the container. Paths without a leading slash are relative to the WordPress root.",
+			'.'
+		)
+		.allowUnknownOption(true)
+		.action( withSpinner(env.run) )
+
+		
+	// Install Path Command.
+	program.command('install-path')
+		.description('Get the path where all of the environment files are stored. This includes the Docker files, WordPress, PHPUnit files, and any sources that were downloaded.')
+		.allowUnknownOption(true)
+		.action( withSpinner(env.installPath) )
+
+	// Update Plugins Command.
+	program.command('update-plugins')
+		.description('Updates all plugins in the WordPress environment.')
+		.argument('[slug]', 'Plugin slug to update.', 'all')
+		.addOption(new Option('--environment <env>', 'Which environment to use.').choices(['development', 'tests']).default('development'))
+		.allowUnknownOption(true)
+		.action( withSpinner(env.updatePlugins) )
+
+	// Create a Design System Block Command.
+	program.command('create-block')
+		.description('Scaffold for WordPress plugin to register CA.gov Design System Block.')
+		.argument('<slug>', 'Plugin slug to use.')
+		.allowUnknownOption(true)
+		.action( withSpinner(env.createBlock) )
+
+	// Update a Design System Block Command.
+	program.command('update-block')
+		.description('Updates a CA.gov Design System Block.')
+		.argument('<slug>', 'Plugin slug to update.')
+		.allowUnknownOption(true)
+		.action( withSpinner(env.updateBlock) )
+
+	// Test Command.
+	// Ensure this is commented out.
+	program.command('test')
+		.description('Test commands on a WordPress environment')
+		.addArgument(envArg)
+		.option( 
+			'--scripts', 
+			'Execute any configured lifecycle scripts.',
+			true
+		)
+		.allowUnknownOption(true)
+		.action(withSpinner(env.test))
+
+	return program;
 };