@elementor/wp-lite-env 0.0.8 → 0.0.9

package/README.md

@@ -0,0 +1,76 @@
+# wp-lite-env
+A simple, lightweight, docker-based WordPress environment
+
+# Usage
+## Installation
+To install the package, run the following command:
+```bash
+npm install -g @elementor/wp-lite-env
+```
+If you want to install the package for a specific project, run the following command:
+```bash
+npm install --save-dev @elementor/wp-lite-env
+```
+## Creating a configuration file
+The configuration file is a JSON file that contains the configuration for the WordPress environment.
+
+| Field          | Type           | Default | Description                                                                                                                                                |
+|----------------|----------------|---------|------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `"core"`       | `string\|null` | `null`  | The WordPress installation to use. If `null` is specified, the latest production release of WordPress will be used.                                        |
+| `"phpVersion"` | `string\|null` | `null`  | The PHP version to use. If `null` is specified, the latest version of PHP that is compatible with the latest production release of WordPress will be used. |
+| `"plugins"`    | `Object`       | `{}`    | A set of plugins to install and activate in the environment. The entries are a key-value pair in the format of <slug>: <path to plugin>                    |
+| `"themes"`     | `Object`       | `{}`    | A set of themes to install in the environment.  The entries are a key-value pair in the format of <slug>: <path to theme>                                  |
+| `"config"`     | `Object`       | `{}`    | Mapping of wp-config.php constants to their desired values.                                                                                                |
+| `"mappings"`   | `Object`       | `"{}"`  | Mapping of WordPress directories to local directories to be mounted in the WordPress instance.                                                             |
+
+The following is an example of a configuration file:
+```json
+{
+  "core": "6.7",
+  "phpVersion": "8.2",
+  "plugins": {
+    "elementor": "./elementor/build"
+  },
+  "themes": {
+    "hello-elementor": "./hello-elementor"
+  },
+  "mappings": {
+    "resources": "./resources"
+  },
+  "config": {
+    "SCRIPT_DEBUG": false,
+    "WP_DEBUG": false
+  }
+}
+```
+## Usage
+### Starting a new WordPress environment
+To start a new WordPress environment, run the following command:
+```bash
+npx wp-lite-env start config=<path to configuration file> -- port=<port>
+```
+For example:
+```bash
+npx wp-lite-env start config=./tests/.wp-lite-env.json -- port=1234
+```
+### Stopping a WordPress environment
+To stop a running WordPress environment, run the following command:
+```bash
+npx wp-lite-env start config=<path to configuration file> -- port=<port used by the WordPress environment>
+```
+For example:
+```bash
+npx wp-lite-env stop config=./tests/.wp-lite-env.json -- port=1234
+```
+### Starting a new WordPress environment
+The WordPress CLI is available for use on the server. To use it, run the following command:
+```bash
+npx wp-lite-env cli config=<path to configuration file> -- port=<port used by the WordPress environment> command="<CLI command>"
+```
+For example:
+```bash
+npx wp-lite-env cli config=./tests/.wp-lite-env.json -- port=1234 command="ls -la /var/www/html"
+```
+
+# Contributors
+This package is developed and maintained by the [Elementor](https://elementor.com) team. With that being said, we want to thank the [@wordpress/env](https://www.npmjs.com/package/@wordpress/env) team, this package is heavily inspired by their wonderful work.

package/__tests__/__snapshots__/template.test.ts.snap

@@ -0,0 +1,71 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`templates compose file generation snapshot test 1`] = `
+"services:
+  mysql:
+    image: 'mariadb:lts'
+    ports:
+      - '\${WP_ENV_MYSQL_PORT:-}:3306'
+    environment:
+      MYSQL_ROOT_HOST: '%'
+      MYSQL_ROOT_PASSWORD: password
+      MYSQL_DATABASE: wordpress
+    volumes:
+      - 'mysql:/var/lib/mysql'
+  wordpress:
+    depends_on:
+      - mysql
+    build:
+      context: .
+      dockerfile: WordPress.Dockerfile
+      no_cache: true
+      args: &ref_0
+        HOST_USERNAME: yotams
+        HOST_UID: '502'
+        HOST_GID: '20'
+    ports:
+      - '\${WP_ENV_PORT:-1234}:80'
+    environment:
+      APACHE_RUN_USER: '#502'
+      APACHE_RUN_GROUP: '#20'
+      WORDPRESS_DB_USER: root
+      WORDPRESS_DB_PASSWORD: password
+      WORDPRESS_DB_NAME: wordpress
+    volumes: &ref_1
+      - >-
+        wpcontent:/var/www/html
+      - >-
+        /some/wp-config/path:/var/www/html/wp-config
+
+    extra_hosts:
+      - 'host.docker.internal:host-gateway'
+  cli:
+    depends_on:
+      - wordpress
+    build:
+      context: .
+      dockerfile: CLI.Dockerfile
+      args: *ref_0
+    volumes: *ref_1
+    user: '502:20'
+    environment:
+      WORDPRESS_DB_USER: root
+      WORDPRESS_DB_PASSWORD: password
+      WORDPRESS_DB_NAME: wordpress
+    extra_hosts:
+      - 'host.docker.internal:host-gateway'
+volumes:
+  mysql: {}
+  wpcontent: {}
+"
+`;
+
+exports[`templates configuration file generation config file is generated with the correct values 1`] = `
+"#!/bin/bash
+set -eox pipefail
+
+wp core install --url="http://localhost:1234" --title="test" --admin_user=admin --admin_password=password --admin_email=wordpress@example.com --skip-email
+wp config set ELEMENTOR_SHOW_HIDDEN_EXPERIMENTS true --raw
+wp config set SCRIPT_DEBUG false --raw
+wp config set WP_DEBUG false --raw"
+`;

package/__tests__/config.test.ts

@@ -0,0 +1,20 @@
+import {describe, expect, jest, test} from '@jest/globals';
+import fs from 'fs';
+import {getConfig} from "../src/config";
+import {MockInstance} from "jest-mock";
+
+jest.mock('fs');
+describe('config', () => {
+    test('defaults', () => {
+        (fs.readFileSync as unknown as MockInstance).mockReturnValueOnce(JSON.stringify({"some" : "data"}));
+        const config = getConfig('some/path');
+        expect(config).toEqual({
+            core: '6.7',
+            phpVersion: '8.1',
+            plugins: {},
+            themes: {},
+            mappings: {},
+            config: {},
+        });
+    });
+});

package/__tests__/e2e.ts

@@ -0,0 +1,21 @@
+import {afterEach, describe, expect, test} from "@jest/globals";
+import {cleanup, generateFiles, getConfigFilePath, start, stop} from "../src/run";
+
+const port = '1234';
+const runPath = (port: string) => {
+    return generateFiles(port, getConfigFilePath(['', '', '', 'config=./tests/.wp-lite-env.json']));
+};
+
+describe('end to end tests', () => {
+    afterEach(async () => {
+        const theRunPath = runPath(port);
+        await stop(port, theRunPath);
+        cleanup(port, theRunPath);
+    }, 30000);
+    test('WordPress is up and running', async () => {
+        await start( port, runPath(port) );
+        const response = await fetch(`http://localhost:${port}`);
+        expect(response.ok).toBe(true);
+        expect(await response.text()).toContain('Welcome to WordPress');
+    }, 60000);
+});

package/__tests__/template.test.ts

@@ -0,0 +1,103 @@
+import {describe, expect, test} from '@jest/globals';
+import {
+    generateCliDockerfileTemplate,
+    generateConfiguration, generateDockerComposeYmlTemplate,
+    generateWordPressDockerfileTemplate
+} from "../src/templates";
+
+describe('templates', () => {
+    describe('docker files', () => {
+        test('WordPress Dockerfile', () => {
+            const core = '1.2';
+            const phpVersion = '3.4';
+            const dockerfile = generateWordPressDockerfileTemplate( { core, phpVersion});
+            expect(dockerfile).toMatch(new RegExp(`^FROM wordpress:${ core }-php${ phpVersion }?`));
+        });
+
+        test('CLI Dockerfile', () => {
+            const phpVersion = '3.4';
+            const dockerfile = generateCliDockerfileTemplate( { phpVersion});
+            expect(dockerfile).toMatch(new RegExp(`^FROM wordpress:cli-php${ phpVersion }?`));
+        });
+    });
+
+    describe('configuration file generation', () => {
+        test('config file is generated with the correct values', () => {
+            const config = {
+                config: {
+                    "ELEMENTOR_SHOW_HIDDEN_EXPERIMENTS": true,
+                    "SCRIPT_DEBUG": false,
+                    "WP_DEBUG": false
+                }
+            };
+            const configTemplate = generateConfiguration( config, '1234' );
+            expect(configTemplate).toMatchSnapshot();
+        });
+    });
+
+    describe('compose file generation', () => {
+        test('snapshot test', () => {
+            const config = {
+                mappings: {},
+                plugins: {},
+                themes: {},
+            }
+            const composeYml = generateDockerComposeYmlTemplate( config, '/some/base/path', '1234', '/some/wp-config/path' );
+            expect(composeYml).toMatchSnapshot();
+        });
+        test('mappings are mounted correctly', () => {
+            const config = {
+                mappings: {
+                    'some/host/path': 'some/container/path',
+                    'some/other/host/path': 'some/other/container/path',
+                },
+                plugins: {},
+                themes: {},
+            }
+            const basePath = '/some/base/path';
+            const composeYml = generateDockerComposeYmlTemplate( config, basePath, '1234', '/some/wp-config/path' );
+            expect(composeYml).toMatch(new RegExp(`${basePath}/some/container/path:/var/www/html/some/host/path`));
+            expect(composeYml).toMatch(new RegExp(`${basePath}/some/other/container/path:/var/www/html/some/other/host/path`));
+        });
+        test('plugins are mounted correctly', () => {
+            const config = {
+                mappings: {
+                },
+                plugins: {
+                    'plugin1': '../some/plugin/path',
+                    'plugin2': '../some/other/plugin/path',
+                },
+                themes: {},
+            }
+            const basePath = '/some/base/path';
+            const composeYml = generateDockerComposeYmlTemplate( config, basePath, '1234', '/some/wp-config/path' );
+            expect(composeYml).toMatch(new RegExp(`/some/base/some/plugin/path:/var/www/html/wp-content/plugins/plugin1`));
+            expect(composeYml).toMatch(new RegExp(`/some/base/some/other/plugin/path:/var/www/html/wp-content/plugins/plugin2`));
+        });
+        test('themes are mounted correctly', () => {
+            const config = {
+                mappings: {},
+                plugins: {},
+                themes: {
+                    'theme1': '../some/theme/path',
+                    'theme2': '../some/other/theme/path',
+                },
+            }
+            const basePath = '/some/base/path';
+            const composeYml = generateDockerComposeYmlTemplate( config, basePath, '1234', '/some/wp-config/path' );
+            expect(composeYml).toMatch(new RegExp(`/some/base/some/theme/path:/var/www/html/wp-content/themes/theme1`));
+            expect(composeYml).toMatch(new RegExp(`/some/base/some/other/theme/path:/var/www/html/wp-content/themes/theme2`));
+        });
+        test('wp-config is mounted correctly', () => {
+            // /some/wp-config/path:/var/www/html/wp-config
+            const config = {
+                mappings: {},
+                plugins: {},
+                themes: {},
+            }
+            const basePath = '/some/base/path';
+            const composeYml = generateDockerComposeYmlTemplate( config, basePath, '1234', '/some/wp-config/path' );
+            expect(composeYml).toMatch(new RegExp(`/some/wp-config/path:/var/www/html/wp-config`));
+        });
+    });
+});

package/dist/package.json

@@ -0,0 +1,46 @@
+{
+    "name": "@elementor/wp-lite-env",
+    "version": "0.0.9",
+    "private": false,
+    "description": "A simple, lightweight, docker-based WordPress environment",
+    "main": "dist/index.js",
+    "type": "module",
+    "types": "dist/index.d.ts",
+    "bin": {
+        "wp-lite-env": "dist/index.js"
+    },
+    "scripts": {
+        "build": "tsc",
+        "lint": "eslint",
+        "release": "npm run build && changeset publish",
+        "test": "jest --coverage=true"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/elementor/wp-lite-env.git"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "author": "Elementor Team",
+    "license": "ISC",
+    "bugs": {
+        "url": "https://github.com/elementor/wp-lite-env/issues"
+    },
+    "homepage": "https://github.com/elementor/wp-lite-env#readme",
+    "dependencies": {
+        "docker-compose": "^1.1.0"
+    },
+    "devDependencies": {
+        "@changesets/cli": "^2.27.9",
+        "@eslint/js": "^9.15.0",
+        "@jest/globals": "^29.7.0",
+        "@types/eslint__js": "^8.42.3",
+        "@types/node": "^22.9.0",
+        "eslint": "~9.14.0",
+        "jest": "^29.7.0",
+        "ts-jest": "^29.2.5",
+        "typescript": "^5.6.3",
+        "typescript-eslint": "^8.14.0"
+    }
+}

package/eslint.config.mjs

@@ -0,0 +1,13 @@
+// @ts-check
+
+import eslint from '@eslint/js';
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+    {
+        // config with just ignores is the replacement for `.eslintignore`
+        ignores: ['dist/**', '**.js', '**.map'],
+    },
+    eslint.configs.recommended,
+    ...tseslint.configs.recommended,
+);

package/index.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+
+import {cleanup, commandMap, generateFiles, getCliCommand, getConfigFilePath, getPort} from './src/run';
+
+const command = process.argv[ 2 ];
+if ( ! commandMap[ command ] ) {
+	console.log( `Valid commands: ${ Object.keys( commandMap ).join( ', ' ) }. You used ${ command }` );
+}
+
+const port = getPort( process.argv );
+const configFilePath = getConfigFilePath( process.argv )
+const runPath = generateFiles( port, configFilePath );
+const cliCommand = getCliCommand( process.argv );
+
+try {
+	await commandMap[command](port, runPath, cliCommand);
+} finally {
+	cleanup( port, runPath );
+}

package/jest.config.js

@@ -0,0 +1,8 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} **/
+export default {
+  testEnvironment: "node",
+  testPathIgnorePatterns: ["<rootDir>/dist/", "<rootDir>/node_modules/"],
+  transform: {
+    "^.+.tsx?$": ["ts-jest",{}],
+  },
+};

package/package.json

@@ -1,47 +1,46 @@
 {
-    "name": "@elementor/wp-lite-env",
-    "version": "0.0.8",
-    "private": false,
-    "description": "A simple, lightweight, docker-based WordPress environment",
-    "main": "dist/index.js",
-    "type": "module",
-    "types": "dist/index.d.ts",
-    "bin": {
-        "wp-lite-env": "dist/index.js"
-    },
-    "scripts": {
-        "build": "tsc",
-        "lint": "eslint",
-        "release": "npm run build && changeset publish",
-        "test": "jest --coverage=true"
-    },
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/elementor/wp-lite-env.git"
-    },
-    "publishConfig": {
-        "access": "public",
-        "directory": "dist"
-    },
-    "author": "Elementor Team",
-    "license": "ISC",
-    "bugs": {
-        "url": "https://github.com/elementor/wp-lite-env/issues"
-    },
-    "homepage": "https://github.com/elementor/wp-lite-env#readme",
-    "dependencies": {
-        "docker-compose": "^1.1.0"
-    },
-    "devDependencies": {
-        "@changesets/cli": "^2.27.9",
-        "@eslint/js": "^9.15.0",
-        "@jest/globals": "^29.7.0",
-        "@types/eslint__js": "^8.42.3",
-        "@types/node": "^22.9.0",
-        "eslint": "~9.14.0",
-        "jest": "^29.7.0",
-        "ts-jest": "^29.2.5",
-        "typescript": "^5.6.3",
-        "typescript-eslint": "^8.14.0"
-    }
+  "name": "@elementor/wp-lite-env",
+  "version": "0.0.9",
+  "private": false,
+  "description": "A simple, lightweight, docker-based WordPress environment",
+  "main": "dist/index.js",
+  "type": "module",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "wp-lite-env": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "lint": "eslint",
+    "release": "npm run build && changeset publish",
+    "test": "jest --coverage=true"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/elementor/wp-lite-env.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "Elementor Team",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/elementor/wp-lite-env/issues"
+  },
+  "homepage": "https://github.com/elementor/wp-lite-env#readme",
+  "dependencies": {
+    "docker-compose": "^1.1.0"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.27.9",
+    "@eslint/js": "^9.15.0",
+    "@jest/globals": "^29.7.0",
+    "@types/eslint__js": "^8.42.3",
+    "@types/node": "^22.9.0",
+    "eslint": "~9.14.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.5",
+    "typescript": "^5.6.3",
+    "typescript-eslint": "^8.14.0"
+  }
 }

package/src/config.ts

@@ -0,0 +1,35 @@
+import fs from 'fs';
+
+export type Config = {
+	core?: string,
+	phpVersion?: string,
+	plugins?: { [key: string]: string },
+	themes?: { [key: string]: string },
+	mappings?: { [key: string]: string },
+	config?: Record<string, string|boolean>,
+}
+
+export const getConfig = ( configFilePath?: string ): Config => {
+	let configFile: Config = {};
+	if ( configFilePath ) {
+		configFile = JSON.parse( fs.readFileSync( configFilePath, 'utf8' ) ) as Config;
+	}
+
+	const defaultConfig: Config = {
+		core: '6.7',
+		phpVersion: '8.1',
+		plugins: {},
+		themes: {},
+		mappings: {},
+		config: {},
+	};
+
+	return {
+		core: configFile.core || defaultConfig.core,
+		phpVersion: configFile.phpVersion || defaultConfig.phpVersion,
+		plugins: configFile.plugins || defaultConfig.plugins,
+		themes: configFile.themes || defaultConfig.themes,
+		mappings: configFile.mappings || defaultConfig.mappings,
+		config: configFile.config || defaultConfig.config,
+	};
+};

package/src/run.ts

@@ -0,0 +1,125 @@
+import {downAll, run, upAll} from "docker-compose";
+import path from "path";
+import {getConfig} from "./config";
+import fs from "fs";
+import {
+    generateCliDockerfileTemplate,
+    generateConfiguration,
+    generateDockerComposeYmlTemplate,
+    generateWordPressDockerfileTemplate
+} from "./templates";
+import {createHash} from "crypto";
+import os from "node:os";
+
+const waitForServer = async ( url: string, timeoutMs: number ) => {
+    const startTime = Date.now();
+    const sleep = ( ms: number ) => new Promise( ( r ) => setTimeout( r, ms ) );
+
+    while ( startTime + timeoutMs > Date.now() ) {
+        try {
+            const response = await fetch( url );
+            if ( response.ok && ( 200 === response.status || 302 === response.status ) ) {
+                return true;
+            }
+        } catch ( e ) { // eslint-disable-line @typescript-eslint/no-unused-vars
+            // Ignore
+        } finally {
+            await sleep( 100 );
+        }
+    }
+    return false;
+};
+
+export const start = async ( port: string, runPath: string ) => {
+    await upAll( {
+        commandOptions: [ '--build' ],
+        composeOptions: [ '-p', `port${ port }` ],
+        cwd: runPath,
+        log: true,
+    } );
+    await waitForServer( `http://localhost:${ port }`, 10000 );
+    await cli( port, runPath, 'bash wp-config/configure-wp.sh' );
+};
+
+export const stop = async ( port: string, runPath: string ) => {
+    await downAll( {
+        cwd: runPath,
+        commandOptions: [ '--volumes', '--remove-orphans' ],
+        composeOptions: [ '-p', `port${ port }` ],
+        log: true,
+    } );
+};
+
+const cli = async ( port: string, runPath: string, command: string ) => {
+    await run( 'cli', command, {
+        cwd: runPath,
+        commandOptions: [ '--rm' ],
+        composeOptions: [ '-p', `port${ port }` ],
+        log: true,
+    } );
+};
+
+export const commandMap: { [key: string]: ( ( port: string ) => Promise<void> ) | ( ( port: string, runPath: string, command: string ) => Promise<void> ) } = {
+    start,
+    stop,
+    cli,
+};
+
+const getWpConfigPath = ( port: string ) => path.resolve( process.cwd(), port );
+
+export const generateFiles = ( port: string, configFilePath: string ) => {
+    const config = getConfig( configFilePath );
+
+    // Using a local path since Docker Compose cannot access /tmp
+    // See: https://github.com/docker/compose/issues/1153
+    const wpConfigPath = getWpConfigPath( port );
+    if ( ! fs.existsSync( wpConfigPath ) ) {
+        fs.mkdirSync( wpConfigPath, { recursive: true } );
+    }
+    const wpConfig = generateConfiguration( config, port );
+    fs.writeFileSync( path.resolve( wpConfigPath, 'configure-wp.sh' ), wpConfig );
+
+    const dockerComposeYmlTemplate = generateDockerComposeYmlTemplate( config, process.cwd(), port, wpConfigPath );
+    const wordPressDockerfileTemplate = generateWordPressDockerfileTemplate( config );
+    const cliDockerfileTemplate = generateCliDockerfileTemplate( config );
+    const hash = createHash( 'sha256' );
+    hash.update( dockerComposeYmlTemplate + wordPressDockerfileTemplate + cliDockerfileTemplate + port );
+    const runPath = path.resolve( os.tmpdir(), `${ hash.digest( 'hex' ) }` );
+    if ( ! fs.existsSync( runPath ) ) {
+        fs.mkdirSync( runPath );
+    }
+
+    console.log( `writing files to run path: ${ runPath }` );
+    fs.writeFileSync( path.resolve( runPath, 'docker-compose.yml' ), dockerComposeYmlTemplate );
+    fs.writeFileSync( path.resolve( runPath, 'WordPress.Dockerfile' ), wordPressDockerfileTemplate );
+    fs.writeFileSync( path.resolve( runPath, 'CLI.Dockerfile' ), cliDockerfileTemplate );
+
+    return runPath;
+};
+
+const getArgument = ( argumentKey: string, processArgs: string[] ) => {
+    for ( let i = 3; i < processArgs.length; i++ ) {
+        const argument = processArgs[ i ];
+        if ( argument.startsWith( `${ argumentKey }=` ) ) {
+            return argument.substring( argumentKey.length + 1 );
+        }
+    }
+    return undefined;
+};
+
+export const getConfigFilePath = ( processArgs: string[] ) => {
+    return path.resolve(getArgument( 'config', processArgs ));
+};
+
+export const getCliCommand = ( processArgs: string[] ) => {
+    return getArgument( 'command', processArgs );
+};
+
+export const getPort = ( processArgs: string[] ) => {
+    return getArgument( 'port', processArgs ) || '8888';
+};
+
+export const cleanup = ( port: string, runPath: string ) => {
+    fs.rmSync( getWpConfigPath( port ), { recursive: true, force: true } );
+    fs.rmSync( runPath, { recursive: true, force: true } );
+}