Introduce a new @wp-playground/common package to avoid circular depen…

…cies (#1387)

Rationale: I couldn't add a `installSqlitePlugin` function to
`@wp-playground/wordpress` as it imported Blueprints which already
relied on `@wp-playground/wordpress`.

The new `@wp-playground/common` package should give us some leeway to
start implementing parts of the boot pipeline similarly to
`@php-wasm/util`.

As a side note, I'm not a fan of these "common" packages as they tend to
grow indefinitely overtime and attract every bit of code that doesn't
fit anywhere else. Let's be extra careful when adding new "common"
functions and always ask "is my design right? could this be structured
differently? before adding more code.

## Testing instructions

Confirm the unit tests pass

packages/php-wasm/node/src/test/php-process-manager.spec.ts

@@ -1,4 +1,4 @@
-import { RecommendedPHPVersion } from '@wp-playground/wordpress';
+import { RecommendedPHPVersion } from '@wp-playground/common';
 import { NodePHP } from '..';
 import { PHPProcessManager } from '@php-wasm/universal';
 

packages/php-wasm/node/src/test/php-request-handler.spec.ts

@@ -1,4 +1,4 @@
-import { RecommendedPHPVersion } from '@wp-playground/wordpress';
+import { RecommendedPHPVersion } from '@wp-playground/common';
 import { NodePHP } from '..';
 import { PHPRequestHandler, SupportedPHPVersions } from '@php-wasm/universal';
 import { createSpawnHandler } from '@php-wasm/util';

packages/playground/blueprints/src/lib/compile.spec.ts

@@ -5,7 +5,7 @@ import {
 	validateBlueprint,
 } from './compile';
 import { defineWpConfigConsts } from './steps/define-wp-config-consts';
-import { RecommendedPHPVersion } from '@wp-playground/wordpress';
+import { RecommendedPHPVersion } from '@wp-playground/common';
 import { PHPRequestHandler } from '@php-wasm/universal';
 
 describe('Blueprints', () => {

packages/playground/blueprints/src/lib/steps/activate-plugin.spec.ts

@@ -1,5 +1,5 @@
 import { NodePHP } from '@php-wasm/node';
-import { RecommendedPHPVersion } from '@wp-playground/wordpress';
+import { RecommendedPHPVersion } from '@wp-playground/common';
 import { getWordPressModule } from '@wp-playground/wordpress-builds';
 import { unzip } from './unzip';
 import { activatePlugin } from './activate-plugin';

packages/playground/blueprints/src/lib/steps/activate-theme.spec.ts

@@ -1,5 +1,5 @@
 import { NodePHP } from '@php-wasm/node';
-import { RecommendedPHPVersion } from '@wp-playground/wordpress';
+import { RecommendedPHPVersion } from '@wp-playground/common';
 import { getWordPressModule } from '@wp-playground/wordpress-builds';
 import { unzip } from './unzip';
 import { activateTheme } from './activate-theme';

packages/playground/blueprints/src/lib/steps/cp.spec.ts

@@ -1,5 +1,5 @@
 import { NodePHP } from '@php-wasm/node';
-import { RecommendedPHPVersion } from '@wp-playground/wordpress';
+import { RecommendedPHPVersion } from '@wp-playground/common';
 import { cp } from './cp';
 
 const docroot = '/php';

packages/playground/blueprints/src/lib/steps/define-wp-config-consts.spec.ts

@@ -1,6 +1,6 @@
 import { NodePHP } from '@php-wasm/node';
 import { rewriteDefineCalls, defineBeforeRun } from './define-wp-config-consts';
-import { RecommendedPHPVersion } from '@wp-playground/wordpress';
+import { RecommendedPHPVersion } from '@wp-playground/common';
 
 describe('rewriteDefineCalls', () => {
 	let php: NodePHP;

packages/playground/blueprints/src/lib/steps/enable-multisite.spec.ts

@@ -1,5 +1,5 @@
 import { NodePHP } from '@php-wasm/node';
-import { RecommendedPHPVersion } from '@wp-playground/wordpress';
+import { RecommendedPHPVersion } from '@wp-playground/common';
 import { getWordPressModule } from '@wp-playground/wordpress-builds';
 import { unzip } from './unzip';
 import { enableMultisite } from './enable-multisite';

packages/playground/blueprints/src/lib/steps/import-wxr.spec.ts

@@ -1,5 +1,5 @@
 import { NodePHP } from '@php-wasm/node';
-import { RecommendedPHPVersion } from '@wp-playground/wordpress';
+import { RecommendedPHPVersion } from '@wp-playground/common';
 import { getWordPressModule } from '@wp-playground/wordpress-builds';
 import { importWxr } from './import-wxr';
 import { readFile } from 'fs/promises';

packages/playground/blueprints/src/lib/steps/install-plugin.spec.ts

@@ -1,5 +1,5 @@
 import { NodePHP } from '@php-wasm/node';
-import { RecommendedPHPVersion } from '@wp-playground/wordpress';
+import { RecommendedPHPVersion } from '@wp-playground/common';
 import { installPlugin } from './install-plugin';
 import { phpVar } from '@php-wasm/util';
 import { PHPRequestHandler } from '@php-wasm/universal';

packages/playground/blueprints/src/lib/steps/install-theme.spec.ts

@@ -1,5 +1,5 @@
 import { NodePHP } from '@php-wasm/node';
-import { RecommendedPHPVersion } from '@wp-playground/wordpress';
+import { RecommendedPHPVersion } from '@wp-playground/common';
 import { installTheme } from './install-theme';
 import { PHPRequestHandler } from '@php-wasm/universal';
 

packages/playground/blueprints/src/lib/steps/login.spec.ts

@@ -1,5 +1,5 @@
 import { NodePHP } from '@php-wasm/node';
-import { RecommendedPHPVersion } from '@wp-playground/wordpress';
+import { RecommendedPHPVersion } from '@wp-playground/common';
 import { getWordPressModule } from '@wp-playground/wordpress-builds';
 import { login } from './login';
 import { unzip } from './unzip';

packages/playground/blueprints/src/lib/steps/mkdir.spec.ts

@@ -1,5 +1,5 @@
 import { NodePHP } from '@php-wasm/node';
-import { RecommendedPHPVersion } from '@wp-playground/wordpress';
+import { RecommendedPHPVersion } from '@wp-playground/common';
 import { mkdir } from './mkdir';
 
 describe('Blueprint step mkdir', () => {

packages/playground/blueprints/src/lib/steps/mv.spec.ts

@@ -1,5 +1,5 @@
 import { NodePHP } from '@php-wasm/node';
-import { RecommendedPHPVersion } from '@wp-playground/wordpress';
+import { RecommendedPHPVersion } from '@wp-playground/common';
 import { mv } from './mv';
 
 const docroot = '/php';

packages/playground/blueprints/src/lib/steps/rm.spec.ts

@@ -1,5 +1,5 @@
 import { NodePHP } from '@php-wasm/node';
-import { RecommendedPHPVersion } from '@wp-playground/wordpress';
+import { RecommendedPHPVersion } from '@wp-playground/common';
 import { rm } from './rm';
 
 const docroot = '/php';

packages/playground/blueprints/src/lib/steps/site-data.spec.ts

@@ -1,5 +1,5 @@
 import { NodePHP } from '@php-wasm/node';
-import { RecommendedPHPVersion } from '@wp-playground/wordpress';
+import { RecommendedPHPVersion } from '@wp-playground/common';
 import { getWordPressModule } from '@wp-playground/wordpress-builds';
 import { setSiteOptions } from './site-data';
 import { unzip } from './unzip';

packages/playground/cli/src/cli.ts

@@ -21,7 +21,7 @@ import {
 import { NodePHP } from '@php-wasm/node';
 import { isValidWordPressSlug } from './is-valid-wordpress-slug';
 import { EmscriptenDownloadMonitor, ProgressTracker } from '@php-wasm/progress';
-import { RecommendedPHPVersion } from '@wp-playground/wordpress';
+import { RecommendedPHPVersion } from '@wp-playground/common';
 
 export interface Mount {
 	hostPath: string;

packages/playground/common/.eslintrc.json

@@ -0,0 +1,32 @@
+{
+	"extends": ["../../../.eslintrc.json"],
+	"ignorePatterns": ["!**/*"],
+	"overrides": [
+		{
+			"files": ["*.ts", "*.tsx", "*.js", "*.jsx"],
+			"rules": {}
+		},
+		{
+			"files": ["*.ts", "*.tsx"],
+			"rules": {}
+		},
+		{
+			"files": ["*.js", "*.jsx"],
+			"rules": {}
+		},
+		{
+			"files": ["*.json"],
+			"parser": "jsonc-eslint-parser",
+			"rules": {
+				"@nx/dependency-checks": [
+					"error",
+					{
+						"ignoredFiles": [
+							"{projectRoot}/vite.config.{js,ts,mjs,mts}"
+						]
+					}
+				]
+			}
+		}
+	]
+}

packages/playground/common/README.md

@@ -0,0 +1,14 @@
+# Playground common
+
+This package contains common code for the playground packages
+that doesn't fit in any other package. For example, the
+`RecommendedPHPVersion` is imported virtually everywhere
+and including it in any other specific package would result
+in a lot of circular dependencies.
+
+Avoid adding new code to this package. @wp-playground/common should remain
+as lean as possible. It only exists to avoid circular dependencies. Let's not
+use it as a default place to add code that doesn't seem to fit
+anywhere else. If there's no good place for your code, perhaps
+it needs to be restructured? Or maybe there's a need for a new package?
+Let's always consider these questions before adding new code here.

packages/playground/common/package.json

@@ -0,0 +1,30 @@
+{
+	"name": "@wp-playground/common",
+	"version": "0.7.19",
+	"description": "Common exports and utilities for WordPress Playground",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/common/common-playground"
+	},
+	"homepage": "https://developer.wordpress.org/playground",
+	"author": "The WordPress contributors",
+	"contributors": [
+		{
+			"name": "Adam Zielinski",
+			"email": "adam@adamziel.com",
+			"url": "https://github.com/adamziel"
+		}
+	],
+	"main": "./index.js",
+	"typings": "./index.d.ts",
+	"license": "GPL-2.0-or-later",
+	"type": "module",
+	"engines": {
+		"node": ">=18.18.0",
+		"npm": ">=8.11.0"
+	},
+	"publishConfig": {
+		"access": "public",
+		"directory": "../../../dist/packages/playground/common"
+	}
+}

packages/playground/common/project.json

@@ -0,0 +1,56 @@
+{
+	"name": "playground-common",
+	"$schema": "../../../node_modules/nx/schemas/project-schema.json",
+	"sourceRoot": "packages/playground/common/src",
+	"projectType": "library",
+	"targets": {
+		"build": {
+			"executor": "@nx/vite:build",
+			"outputs": ["{options.outputPath}"],
+			"defaultConfiguration": "production",
+			"options": {
+				"outputPath": "dist/packages/playground/common"
+			},
+			"configurations": {
+				"development": {
+					"mode": "development"
+				},
+				"production": {
+					"mode": "production"
+				}
+			},
+			"dependsOn": ["^build"]
+		},
+		"publish": {
+			"executor": "nx:run-commands",
+			"options": {
+				"command": "node tools/scripts/publish.mjs playground-common {args.ver} {args.tag}",
+				"parallel": false
+			},
+			"dependsOn": ["build"]
+		},
+		"test": {
+			"executor": "nx:noop",
+			"dependsOn": ["test:vite"]
+		},
+		"test:vite": {
+			"executor": "@nx/vite:test",
+			"outputs": ["{workspaceRoot}/coverage/packages/playground/common"],
+			"options": {
+				"passWithNoTests": true,
+				"reportsDirectory": "../../../coverage/packages/playground/common"
+			}
+		},
+		"lint": {
+			"executor": "@nx/linter:eslint",
+			"outputs": ["{options.outputFile}"],
+			"options": {
+				"lintFilePatterns": [
+					"packages/playground/common/**/*.ts",
+					"packages/playground/common/package.json"
+				]
+			}
+		}
+	},
+	"tags": []
+}

packages/playground/common/src/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Avoid adding new code here. @wp-playground/common should remain
+ * as lean as possible.
+ *
+ * This package exists to avoid circular dependencies. Let's not
+ * use it as a default place to add code that doesn't seem to fit
+ * anywhere else. If there's no good place for your code, perhaps
+ * it needs to be restructured? Or maybe there's a need for a new package?
+ * Let's always consider these questions before adding new code here.
+ */
+
+export const RecommendedPHPVersion = '8.0';

packages/playground/common/tsconfig.json

@@ -0,0 +1,23 @@
+{
+	"extends": "../../../tsconfig.base.json",
+	"compilerOptions": {
+		"module": "ES2022",
+		"forceConsistentCasingInFileNames": true,
+		"strict": true,
+		"noImplicitOverride": true,
+		"noPropertyAccessFromIndexSignature": true,
+		"noImplicitReturns": true,
+		"noFallthroughCasesInSwitch": true,
+		"types": ["vitest"]
+	},
+	"files": [],
+	"include": [],
+	"references": [
+		{
+			"path": "./tsconfig.lib.json"
+		},
+		{
+			"path": "./tsconfig.spec.json"
+		}
+	]
+}

packages/playground/common/tsconfig.lib.json

@@ -0,0 +1,10 @@
+{
+	"extends": "./tsconfig.json",
+	"compilerOptions": {
+		"outDir": "../../../dist/out-tsc",
+		"declaration": true,
+		"types": ["node", "vite/client"]
+	},
+	"include": ["src/**/*.ts"],
+	"exclude": ["jest.config.ts", "src/**/*.spec.ts", "src/**/*.test.ts"]
+}

packages/playground/common/tsconfig.spec.json

@@ -0,0 +1,27 @@
+{
+	"extends": "./tsconfig.json",
+	"compilerOptions": {
+		"outDir": "../../dist/out-tsc",
+		"types": [
+			"vitest/globals",
+			"vitest/importMeta",
+			"vite/client",
+			"node",
+			"vitest"
+		]
+	},
+	"include": [
+		"vite.config.ts",
+		"src/*.test.ts",
+		"src/*.spec.ts",
+		"src/**/*.test.ts",
+		"src/**/*.spec.ts",
+		"src/**/*.test.tsx",
+		"src/**/*.spec.tsx",
+		"src/**/*.test.js",
+		"src/**/*.spec.js",
+		"src/**/*.test.jsx",
+		"src/**/*.spec.jsx",
+		"src/**/*.d.ts"
+	]
+}

packages/playground/common/vite.config.ts

@@ -0,0 +1,55 @@
+/// <reference types='vitest' />
+import { defineConfig } from 'vite';
+import dts from 'vite-plugin-dts';
+// eslint-disable-next-line @nx/enforce-module-boundaries
+import { viteTsConfigPaths } from '../../vite-ts-config-paths';
+
+const path = (filename: string) => new URL(filename, import.meta.url).pathname;
+export default defineConfig({
+	assetsInclude: ['**/*.wasm', '*.zip'],
+	cacheDir: '../../../node_modules/.vite/playground-common',
+	plugins: [
+		viteTsConfigPaths({
+			root: '../../../',
+		}),
+		dts({
+			entryRoot: 'src',
+			tsconfigPath: path('tsconfig.lib.json'),
+		}),
+	],
+
+	build: {
+		target: 'esnext',
+		// Important: Vite does not extract static assets as separate files
+		//            in the library mode. assetsInlineLimit: 0 only works
+		//            in the app mode.
+		// @see https://github.com/vitejs/vite/issues/3295
+		assetsInlineLimit: 0,
+		rollupOptions: {
+			input: path('src/index.ts'),
+			// These additional options are required to preserve
+			// all the exports from the entry point. Otherwise,
+			// vite only preserves the ones it considers to be used.
+			output: {
+				name: 'exportsFromEntryPoint',
+				// Ensure the main entry point always gets output as index.js
+				entryFileNames: (chunkInfo: any) => {
+					if (chunkInfo.name === 'index') {
+						return 'index.js';
+					}
+					return '[name]-[hash].js';
+				},
+			},
+			preserveEntrySignatures: 'strict',
+		},
+	},
+
+	test: {
+		globals: true,
+		cache: {
+			dir: '../../../node_modules/.vitest',
+		},
+		environment: 'node',
+		include: ['src/**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}'],
+	},
+});

packages/playground/sync/src/test/sql.spec.ts

@@ -5,7 +5,7 @@ import {
 	journalSQLQueries,
 } from '../sql';
 import { getWordPressModule } from '@wp-playground/wordpress-builds';
-import { RecommendedPHPVersion } from '@wp-playground/wordpress';
+import { RecommendedPHPVersion } from '@wp-playground/common';
 import { unzip } from '@wp-playground/blueprints';
 
 describe('Sync tests', () => {