@caweb/cli 1.1.0 → 1.3.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,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 import cli from '../lib/cli.js';
 

package/commands/a11y.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+
+/**
+ * External dependencies
+ */
+import path from 'path';
+import fs from 'fs';
+import resolveBin from 'resolve-bin';
+
+/**
+ * Internal dependencies
+ */
+// Our default A11y Checker Configuration 
+import defaultConfig from '../configs/aceconfig.js';
+
+import { 
+    runCmd, 
+} from '../lib/index.js';
+
+
+
+/**
+ * Run accessibility checks
+ * 
+ * @param {Object}  options
+ * @param {Object}  options.spinner A CLI spinner which indicates progress.
+ * @param {boolean} options.debug   True if debug mode is enabled.
+ */
+export default async function a11y({
+	spinner,
+	debug, 
+} ) {
+
+    // Spinner not needed at the moment
+	spinner.stop()
+    const {
+        ruleArchive,
+        policies,
+        failLevels,
+        reportLevels,
+        outputFolder,
+        outputFormat,
+        outputFilenameTimestamp
+    } = defaultConfig;
+
+    
+    // pass any arguments from the cli
+    // overwriting our default config flags.
+    // users can overwrite any values by creating a .achecker.yml or aceconfig.js.
+    let acheckerArgs = [
+        '--ruleArchive',
+        ruleArchive,
+        '--policies',
+        Array.isArray(policies) ? policies.join(',') : policies,
+        '--failLevels',
+        Array.isArray(failLevels) ? failLevels.join(',') : failLevels,
+        '--reportLevels',
+        Array.isArray(reportLevels) ? reportLevels.join(',') : reportLevels,
+        '--outputFolder',
+        outputFolder,
+        '--outputFormat',
+        outputFormat,
+        '---outputFilenameTimestamp',
+        outputFilenameTimestamp,
+        process.argv.pop()
+    ];
+
+    // run webpack with our arguments.
+    await runCmd(
+		'achecker', 
+		acheckerArgs, 
+	)
+
+};

package/commands/blocks/create-block.js

@@ -0,0 +1,109 @@
+/**
+ * External dependencies
+ */
+import path from 'path';
+import fs from 'fs';
+import inquirer from 'inquirer';
+
+/**
+ * Internal dependencies
+ */
+import {runCmd, projectPath} from '../../lib/index.js';
+import updateBlock from './update-block.js';
+
+const localFile = path.join(projectPath, 'package.json');
+const pkg = JSON.parse( fs.readFileSync(localFile) );
+
+/**
+ * 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.join(projectPath, '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.join(process.cwd(), slug ),
+						stdio: 'inherit'
+					}
+				)
+				
+				spinner.text = spinnerText;
+
+			}
+		}
+		
+		
+};

package/commands/blocks/update-block.js

@@ -0,0 +1,60 @@
+/**
+ * External dependencies
+ */
+import path from 'path';
+import fs from 'fs';
+
+/**
+ * Internal dependencies
+ */
+import createBlock from './create-block.js';
+
+/**
+ * Update 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/commands/build.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+
+/**
+ * External dependencies
+ */
+import path from 'path';
+import fs from 'fs';
+
+/**
+ * Internal dependencies
+ */
+import { 
+    runCmd, 
+    projectPath,
+    appPath
+} from '../lib/index.js';
+
+
+/**
+ * Build the current project
+ * 
+ * @param {Object}  options
+ * @param {Object}  options.spinner A CLI spinner which indicates progress.
+ * @param {boolean} options.debug   True if debug mode is enabled.
+ */
+export default async function build({
+	spinner,
+	debug, 
+} ) {
+
+    // Spinner not needed at the moment
+	spinner.stop()
+
+    // Since we use @wordpress/scripts webpack config we can leverage
+    // the environment variables as well.
+    process.env.WP_COPY_PHP_FILES_TO_DIST  = true;
+
+    // Our default Webpack Configuration 
+    const defaultConfig = path.join( projectPath, 'configs', 'webpack.config.js' );
+
+    // pass any arguments from the cli
+    // add our default config as an extension.
+    // users can overwrite any values by creating a webconfig of their own.
+    let webPackArgs = [
+        '--mode=none',
+        '--progress',
+        '--config',
+        defaultConfig
+    ];
+
+    // CommonJS
+    if( fs.existsSync( path.join(appPath, 'webpack.config.cjs' ))){
+        webPackArgs.push(
+            '--config',
+            path.join(appPath, 'webpack.config.cjs' ),
+            '--merge'
+        )
+    // ESM
+    }else if( fs.existsSync(path.join(appPath, 'webpack.config.js' )) ){
+        webPackArgs.push(
+            '--config',
+            path.join(appPath, 'webpack.config.js' ),
+            '--merge'
+        )
+    }
+
+    // run webpack with our arguments.
+    await runCmd(
+		'webpack', 
+		webPackArgs, 
+	)
+
+};

package/commands/env/destroy.js

@@ -0,0 +1,49 @@
+
+/**
+ * External dependencies
+ */
+import { default as wpEnvDestroy } from '@wordpress/env/lib/commands/destroy.js';
+
+/**
+ * Internal dependencies
+ */
+import { runCmd } from '../../lib/index.js';
+
+/**
+ * Destroys the development server.
+ * 
+ * @param {Object}  options
+ * @param {Object}  options.spinner A CLI spinner which indicates progress.
+ * @param {boolean} options.scripts Indicates whether or not lifecycle scripts should be executed.
+ * @param {boolean} options.debug   True if debug mode is enabled.
+ * 
+ */
+export default async function destroy({
+	spinner,
+	scripts,
+	debug,
+}) {
+
+	await wpEnvDestroy({spinner, scripts, debug });
+
+	// wp-env destroy completed successfully if spinner.text reads.
+	if( 'Removed WordPress environment.' === spinner.text ){
+		spinner.text = "Cleaning up...";
+		
+		// Stop phpMyAdmin as well
+		// wp-env doesn't destroy the phpmyadmin image so we have to do it ourselves.
+		await runCmd(
+			'docker',
+			[
+				'image',
+				'rm',
+				'phpmyadmin'
+			],
+			{ stdio: 'ignore' }
+		)
+		
+		spinner.text = "Removed WordPress environment.'";
+
+	}
+
+}

package/{lib/commands → commands/env}/start.js

@@ -1,36 +1,34 @@
-import path from 'node:path';
-import util from 'node:util';
-import fs from 'fs-extra';
+/**
+ * External dependencies
+ */
+import path from 'path';
+import fs from 'fs';
+import { v2 as dockerCompose } from 'docker-compose';
 import yaml from 'js-yaml';
-import dockerCompose from 'docker-compose';
 
+/**
+ * WordPress dependencies
+ */
 import { default as wpEnvStart} from '@wordpress/env/lib/commands/start.js';
-import {	
-	checkDatabaseConnection, 
-	canAccessWPORG 
-} from '@wordpress/env/lib/wordpress.js';
-
+import loadConfig from '@wordpress/env/lib/config/load-config.js';
 import retry from '@wordpress/env/lib/retry.js';
+import { didCacheChange, getCache } from '@wordpress/env/lib/cache.js';
+import { canAccessWPORG } from '@wordpress/env/lib/wordpress.js';
 
 const CONFIG_CACHE_KEY = 'config_checksum';
 
-import loadConfig from '@wordpress/env/lib/config/load-config.js';
-import { didCacheChange, getCache } from '@wordpress/env/lib/cache.js';
-
 /**
  * Internal dependencies
  */
+import { appPath } from '../../lib/helpers.js';
+import wpEnvConfig from '../../configs/wp-env.js';
+import dockerConfig from '../../configs/docker-compose.js';
 
-import { configureCAWeb } from '../caweb.js';
-import {downloadSources } from '../download-sources.js';
-import { configureWordPress } from '../wordpress.js';
-import { buildWPEnvConfig, buildDockerComposeConfig } from '../configs.js';
-
-/**
- * Promisified dependencies
- */
-const sleep = util.promisify( setTimeout );
-const { writeFile } = fs.promises;
+import { 
+	configureCAWeb,
+	downloadSources,
+	configureWordPress
+ } from '../../lib/wordpress/index.js';
 
 /**
  * Starts the development server.
@@ -42,6 +40,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 +53,8 @@ export default async function start({
 	scripts,
 	debug,
 	bare,
+	plugin,
+	theme,
 	multisite,
 	subdomain
 }) {
@@ -60,9 +62,9 @@ export default async function start({
 	spinner.text = 'Writing configuration file...';
 	
 	// Write CAWeb .wp-env.json file.
-	await writeFile(
-		path.join(process.cwd(), '.wp-env.json'),
-		JSON.stringify( buildWPEnvConfig(bare, multisite), null, 4 )
+	fs.writeFileSync(
+		path.join(appPath, '.wp-env.json'),
+		JSON.stringify( wpEnvConfig(bare, multisite, plugin, theme), null, 4 )
 	);
 
 	// Get current wp-env cache key
@@ -103,9 +105,9 @@ export default async function start({
 	}
 		
 	// Write docker-compose.override.yml file to workDirectoryPath.
-	await writeFile(
+	fs.writeFileSync(
 		path.join(workDirectoryPath, 'docker-compose.override.yml'),
-		yaml.dump( buildDockerComposeConfig(workDirectoryPath) )
+		yaml.dump( dockerConfig(workDirectoryPath) )
 	);
 
 	// Only run configurations when config has changed.
@@ -160,6 +162,7 @@ export default async function start({
 	spinner.prefixText = preText + 
 		`phpMyAdmin site started at http://localhost:8080\n\n`;
 
+
 	spinner.text = 'Done!';
 
 };

package/{lib/commands → commands/env}/stop.js

@@ -1,18 +1,12 @@
-import path from 'node:path';
-import { spawn } from 'node:child_process';
+/**
+ * External dependencies
+ */
+import path from 'path';
 import loadConfig from '@wordpress/env/lib/config/load-config.js';
 import { v2 as dockerCompose } from 'docker-compose';
 
 import { default as wpEnvStop } from '@wordpress/env/lib/commands/stop.js';
 
-/**
- * Internal dependencies
- */
-
-/**
- * Promisified dependencies
- */
-
 /**
  * Starts the development server.
  *