@caweb/cli 1.1.0 → 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/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

@@ -7,7 +7,7 @@ import retry from '@wordpress/env/lib/retry.js';
  * Internal dependencies
  */
 import { CAWEB_OPTIONS } from'./options.js';
-import { runCLICmds } from'./docker.js';
+import { runCLICmds } from'./utils.js';
 import { isMultisite } from'./wordpress.js';
 import { configureDivi } from'./divi.js';
 

package/lib/cli.js

@@ -90,6 +90,16 @@ export default function cli() {
 			'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.',
@@ -194,6 +204,20 @@ export default function cli() {
 		.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')

package/lib/commands/blocks/create-block.js

@@ -0,0 +1,110 @@
+/**
+ * External dependencies
+ */
+import path from 'node:path';
+import fs from 'fs-extra';
+import { spawn } from 'node:child_process';
+import inquirer from 'inquirer';
+
+/**
+ * Internal dependencies
+ */
+import {runCmd} from '../../utils.js';
+import updateBlock from './update-block.js';
+
+const localPath = path.resolve( path.join(process.cwd(), 'node_modules/@caweb/cli/package.json') )
+const pkg = JSON.parse( await fs.readFile(localPath) );
+
+/**
+ * Get NPM Package Latest Version
+ * @param {string}  options.slug   Block slug.
+ * @param {Object}  options.spinner A CLI spinner which indicates progress.
+ */
+async function getNPMPackageVersion(pkg, spinner){
+	return await runCmd(
+		'npm',
+		[
+			'view',
+			`${pkg}`,
+			'version'
+		],
+		spinner
+	)
+	
+}
+
+/**
+ * Create Block
+ * 
+ * @param {Object}  options
+ * @param {Object}  options.spinner A CLI spinner which indicates progress.
+ * @param {boolean} options.debug   True if debug mode is enabled.
+ * @param {string} options.slug   Block slug.
+ */
+export default async function createBlock({
+	spinner,
+	debug,
+	slug
+} ) {
+		// if block directory already exists.	
+		if( fs.existsSync(path.resolve(process.cwd(), slug)) ){
+			spinner.info(`${slug} already exists.`)
+
+			const { yesUpdate } = await inquirer.prompt( [
+				{
+					type: 'confirm',
+					name: 'yesUpdate',
+					message: 'Would you like to update it?',
+					default: false,
+				},
+			] );
+
+			if( yesUpdate ){
+				spinner.text = `Updating ${slug}...`;
+				await updateBlock({spinner, debug, slug});
+			}
+		// create a new block
+		}else{
+			// Get cagov component version if it exists.
+			let version = await getNPMPackageVersion(`@cagov/${slug}`, spinner);
+
+			// call the wordpress create-block command using our template.
+			await runCmd(
+				'npx',
+				[
+					`@wordpress/create-block`,
+					slug,
+					'--template=' + path.resolve( path.join(process.cwd(), 'node_modules/@caweb/cli/lib/template/index.cjs') )
+				],
+				spinner,
+				{
+					stdio: 'inherit'
+				}
+			)
+
+			// install cagov npm package if it exists.
+			if( version ){
+				// capture spinner.text result
+				let spinnerText = spinner.text;
+				spinner.text = '';
+
+				await runCmd(
+					'npm',
+					[
+						'install',
+						`@cagov/${slug}@${version}`,
+					],
+					spinner,
+					{
+						cwd: path.resolve( path.join(process.cwd(), slug ) ),
+						stdio: 'inherit'
+					}
+				)
+				
+				spinner.text = spinnerText;
+
+			}
+		}
+		
+		
+};

package/lib/commands/blocks/update-block.js

@@ -0,0 +1,66 @@
+/**
+ * External dependencies
+ */
+import path from 'node:path';
+import fs from 'fs-extra';
+import { spawn } from 'node:child_process';
+
+/**
+ * Internal dependencies
+ */
+import {runCmd} from '../../utils.js';
+import createBlock from './create-block.js';
+
+const localPath = path.resolve( path.join(process.cwd(), 'node_modules/@caweb/cli/package.json') )
+const pkg = JSON.parse( await fs.readFile(localPath) );
+
+
+/**
+ * Create Block
+ * 
+ * @param {Object}  options
+ * @param {Object}  options.spinner A CLI spinner which indicates progress.
+ * @param {boolean} options.debug   True if debug mode is enabled.
+ * @param {string} options.slug   Block slug.
+ */
+export default async function updateBlock({
+	spinner,
+	debug,
+	slug
+} ) {
+	
+		// if block directory exists.	
+		if( fs.existsSync(path.resolve(process.cwd(), slug)) ){
+			spinner.text = `Updating ${slug} block plugin.`;
+
+			// make tmp directory
+			fs.ensureDir( `${slug}.tmp`);
+
+			// move inc directory to tmp directory
+			fs.copySync(`${slug}/inc/`, `${slug}.tmp/inc/`);
+			
+			// move src directory to tmp directory
+			fs.copySync(`${slug}/src/`, `${slug}.tmp/src/`);
+
+			// delete old block.
+			fs.removeSync( `${slug}` );
+
+			// Recreate the block.
+			await createBlock({spinner, debug, slug});
+
+			// move inc directory back to block directory
+			fs.copySync(`${slug}.tmp/inc/`, `${slug}/inc/` );
+			
+			// move src directory back to block directory
+			fs.copySync(`${slug}.tmp/src/`, `${slug}/src/`);
+
+			// delete tmp directory.
+			fs.removeSync( `${slug}.tmp` );
+
+			spinner.succeed(`${slug} has been updated!`); 
+
+		}else{
+			spinner.fail(`${slug} plugin directory not found.`)
+		}			
+		
+};

package/lib/commands/destroy.js

@@ -1,20 +1,12 @@
-import path from 'node:path';
-import loadConfig from '@wordpress/env/lib/config/load-config.js';
-import { spawn } from 'node:child_process';
-import { v2 as dockerCompose } from 'docker-compose';
-
-import { default as wpEnvDestroy } from '@wordpress/env/lib/commands/destroy.js';
-
-/**
- * Internal dependencies
- */
 
 /**
- * Promisified dependencies
+ * External dependencies
  */
+import { spawn } from 'node:child_process';
+import { default as wpEnvDestroy } from '@wordpress/env/lib/commands/destroy.js';
 
 /**
- * Starts the development server.
+ * Destroys the development server.
  * 
  * @param {Object}  options
  * @param {Object}  options.spinner A CLI spinner which indicates progress.
@@ -50,9 +42,7 @@ export default async function destroy({
 
 			childProc.on( 'error', reject );
 			childProc.on( 'exit', ( code ) => {
-				// Code 130 is set if the user tries to exit with ctrl-c before using
-				// ctrl-d (so it is not an error which should fail the script.)
-				if ( code === 0 || code === 130 ) {
+				if ( code === 0 ) {
 					resolve();
 				} else {
 					reject( `Command failed with exit code ${ code }` );

package/lib/commands/index.js

@@ -15,6 +15,8 @@ import installPath from '@wordpress/env/lib/commands/install-path.js';
  */
 import shell from './shell.js';
 import updatePlugins from './tasks/update-plugins.js'
+import createBlock from './blocks/create-block.js'
+import updateBlock from './blocks/update-block.js'
 
 import test from './test.js';
 
@@ -36,5 +38,7 @@ export {
 	destroy,
 	test,
 	shell,
-	updatePlugins
+	updatePlugins,
+	createBlock,
+	updateBlock
 }

package/lib/commands/start.js

@@ -42,6 +42,8 @@ const { writeFile } = fs.promises;
  * @param {boolean} options.scripts Indicates whether or not lifecycle scripts should be executed.
  * @param {boolean} options.debug   True if debug mode is enabled.
  * @param {boolean} options.bare   True if excluding any CAWeb Configurations.
+ * @param {boolean} options.plugin   True if root directory is a plugin.
+ * @param {boolean} options.theme   True if root directory is a theme.
  * @param {boolean} options.multisite   True if converting to multisite.
  * @param {boolean} options.subdomain   True if converting to multisite subdomain.
  * 
@@ -53,6 +55,8 @@ export default async function start({
 	scripts,
 	debug,
 	bare,
+	plugin,
+	theme,
 	multisite,
 	subdomain
 }) {
@@ -62,7 +66,7 @@ export default async function start({
 	// Write CAWeb .wp-env.json file.
 	await writeFile(
 		path.join(process.cwd(), '.wp-env.json'),
-		JSON.stringify( buildWPEnvConfig(bare, multisite), null, 4 )
+		JSON.stringify( buildWPEnvConfig(bare, multisite, plugin, theme), null, 4 )
 	);
 
 	// Get current wp-env cache key

package/lib/commands/tasks/update-plugins.js

@@ -7,7 +7,7 @@ import loadConfig from '@wordpress/env/lib/config/load-config.js';
 /**
  * Internal dependencies
  */
-import {runCLICmds} from '../../docker.js';
+import {runCLICmds} from '../../utils.js';
 
 /**
  * Promisified dependencies

package/lib/commands/test.js

@@ -3,12 +3,14 @@
  */
 import path from 'node:path';
 import loadConfig from '@wordpress/env/lib/config/load-config.js';
+import fs from 'fs-extra';
 
 /**
  * Internal dependencies
  */
-import { runCLICmds } from '../docker.js';
-import { activateCAWeb } from '../caweb.js';
+import { runCLICmds, runCmd } from '../utils.js';
+import generateOverridesMD from '../admin.js';
+import { CAWEB_OPTIONS, DIVI_OPTIONS } from '../options.js';
 
 /**
  * Promisified dependencies
@@ -41,6 +43,4 @@ export default async function test({
 
 		console.log( result );
 
-		spinner.text = "Done!";
-	
 };

package/lib/configs.js

@@ -19,10 +19,15 @@ const pkg = JSON.parse( await fs.readFile(localPath) );
  * 
  * @param {boolean} bare   True if excluding any CAWeb Configurations.
  * @param {boolean} multisite   True if converting to multisite.
+ * @param {boolean} plugin   True if root directory is a plugin.
+ * @param {boolean} theme   True if root directory is a theme.
  * 
  * @returns object
  */
-const buildWPEnvConfig = (bare, multisite) => {
+const buildWPEnvConfig = (bare, multisite, plugin, theme) => {
+    let themes = [];
+    let plugins = [];
+
     let config = {
         core: `WordPress/WordPress#${pkg.config.WP_VER}`,
         phpVersion: `${pkg.config.PHP_VER}`,
@@ -33,12 +38,37 @@ const buildWPEnvConfig = (bare, multisite) => {
 
     // if not bare then include our theme.
     if( ! bare ){
-        config['themes'] = [`CA-CODE-Works/CAWeb`];
+        themes.push('CAWebPublishing/CAWeb')
     }
 
+    // if root directory is a theme
+    if( theme ){
+        themes.push( '.' );
+    }
+    
     // if is multisite
     if( multisite ){
         config.config['WP_ALLOW_MULTISITE'] = true;
+
+        // set CAWeb as Default Theme if it was downloaded
+        if( ! bare ){
+            config.config['WP_DEFAULT_THEME'] = 'CAWeb';
+        }
+    }
+
+    // if root directory is a plugin
+    if( plugin ){
+        plugins.push( '.' );
+    }
+
+    // add plugins if sources were added
+    if( plugins.length ){
+        config['plugins'] = plugins;
+    }
+
+    // add themes if sources were added
+    if( themes.length ){
+        config['themes'] = themes;
     }
 
     return config;

package/lib/divi.js

@@ -1,7 +1,7 @@
 /**
  * Internal dependencies
  */
-import { runCLICmds } from './docker.js';
+import { runCLICmds } from './utils.js';
 import { DIVI_OPTIONS } from './options.js';
 
 

package/lib/download-sources.js

@@ -256,7 +256,7 @@ function dowloadPlugins(pluginDir){
 	return [
 		{
 			basename: 'Design System',
-			url: 'https://github.com/CA-CODE-Works/design-system-wordpress.git',
+			url: 'https://github.com/CAWebPublishing/design-system-wordpress.git',
 			ref: 'main',
 			path: path.join(pluginDir, 'design-system-wordpress'),
 			clonePath: path.join(pluginDir, 'design-system-wordpress'),

package/lib/env.js

@@ -1,17 +1,9 @@
 /**
  * Internal dependencies
  */
-import start from './start.js';
-import destroy from './destroy.js';
-import test from './test.js';
-import shell from './shell.js';
 
-import updatePlugins from './tasks/update-plugins.js'
+import * as commands from './commands/index.js';
 
-export {
-	start,
-	destroy,
-	test,
-	shell,
-	updatePlugins
+export default {
+	...commands
 }

package/lib/options.js

@@ -170,7 +170,7 @@ const github_options = {
 	},
 	CAWEB_GIT_USER: {
 		name: 'caweb_username',
-		defaultValue: 'CA-CODE-Works',
+		defaultValue: 'CAWebPublishing',
 		label: 'Username'
 	},
 	CAWEB_ACCESS_TOKEN: {