@42wp/dev-env 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 João Carvalho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,202 @@
+# 42wp — 42WP dev environments
+
+> *O Guia do Mochileiro do WordPress* — a tiny CLI that spins up disposable
+> WordPress dev environments with Docker, the 42WP way.
+
+`42wp` runs a shared **global layer** (Traefik reverse proxy + MySQL + phpMyAdmin +
+Mailpit) and, on top of it, **per-project** WordPress containers reachable at
+`http://<project>.localhost`. Your current working directory is mounted as
+`wp-content`, so you develop your theme/plugin locally and WordPress runs in a
+container with Xdebug, Memcached and WP-CLI preinstalled.
+
+## Requirements
+
+- [Docker](https://docs.docker.com/get-docker/) with the Compose v2 plugin (`docker compose`)
+- Node.js **>= 18.17**
+
+## Install
+
+```bash
+npm install -g @42wp/dev-env
+```
+
+This installs the `42wp` command globally.
+
+## Usage
+
+```bash
+42wp global start          # start Traefik + MySQL + phpMyAdmin + Mailpit
+42wp start <project>       # build & start a project (run from your theme/plugin repo)
+42wp update <project>      # update an existing project to a newer WordPress image
+42wp wp <project> <args>   # run a WP-CLI command inside the project container
+42wp stop <project>        # stop a project's containers
+42wp rm <project>          # remove a site (container, image, database) — keeps your repo
+42wp seed <project> [n]    # generate demo content in a running project (default 200)
+42wp global stop           # tear the global layer down
+```
+
+Run `42wp` with no arguments for the full command list.
+
+### WordPress version
+
+By default projects are built on **`wordpress:php8.4-apache`** (newest WordPress,
+PHP 8.4, Apache). Pick a different image tag per project with `--wp <tag>`:
+
+```bash
+42wp start my-theme --wp latest             # newest WP, image's default PHP
+42wp start legacy   --wp 6.9-php8.5-apache  # pin a specific WP + PHP
+42wp update my-theme                        # rebuild on the default tag, run wp core update-db
+42wp update my-theme --wp php8.5-apache     # update to a specific image
+```
+
+`update` rewrites the project's Dockerfile, re-pulls the base image, recreates the
+container and runs `wp core update-db` to migrate the schema. Set a different
+default for every project with the `FORTYTWO_WP_TAG` env var.
+
+### Removing a site
+
+`42wp rm <project>` tears a site down completely — its containers, the locally
+built image, and its database — and deletes the generated project dir
+(`~/.42wp/projects/<name>/`, including any cloned VIP mu-plugins). **Your
+repository is never touched**: wp-content is a bind mount of your working
+directory, which Docker leaves alone. It asks for confirmation; skip the prompt
+with `--yes` (or `--force`):
+
+```bash
+42wp rm my-theme          # prompts before removing
+42wp rm my-theme --yes    # no prompt (for scripts/CI)
+```
+
+### Demo content
+
+Seed a project with a full demo dataset using `--demo-content` (defaults to 200
+posts), or set a count with `--demo-content=<n>`:
+
+```bash
+42wp start my-site --demo-content       # ~200 posts
+42wp start my-site --demo-content=50    # 50 posts
+```
+
+It runs a PHP seeder (`wp eval-file`) — no plugin required (FakerPress has no CLI) —
+that creates:
+
+- ~10 `42wp_author` terms (Portuguese names), ~10 tags, ~10 categories
+- a small pool of real images downloaded from [picsum.photos](https://picsum.photos/),
+  reused as featured + inline images
+- posts with rich HTML content (h1/h2/h3, lists, blockquote, images, links), a
+  plain-text excerpt, varied **past** dates, and each linked to 1 category, 2–5
+  tags and 1–3 authors
+
+Works on any project (not just `--vip`). It always creates the requested number of
+posts (it doesn't skip when posts already exist), and a failure never aborts
+`start`. The author terms use the `42wp_author` taxonomy, which the project
+registers itself (e.g. the `42-framework` mu-plugin) — the seeder does not register
+any taxonomy. If `42wp_author` isn't available, the author links are simply skipped.
+
+To add demo content to an **already-running** project without recreating it, use
+`seed`:
+
+```bash
+42wp seed my-site         # 200 posts
+42wp seed my-site 500     # 500 posts
+42wp seed my-site --demo-content=50
+```
+
+### Admin credentials
+
+The silent install creates an `admin` / `password` user by default. Override per
+project on `start`:
+
+```bash
+42wp start my-theme --user joao --pass s3cr3t
+```
+
+### Multisite
+
+Start a site as a WordPress network with `--multisite` (subdirectory) or add
+`--subdomains` for a subdomain network:
+
+```bash
+42wp start my-network --multisite               # sites at my-network.localhost/site2
+42wp start my-network --multisite --subdomains  # sites at site2.my-network.localhost
+```
+
+This installs WordPress, converts it to a network, writes the `MULTISITE` constants
+into `wp-config.php`, and mounts a `.htaccess` with the matching network rewrite
+rules (WP-CLI refuses to generate those for a multisite, which otherwise causes a
+redirect loop on sub-sites). For **subdomain** networks the Traefik router is
+widened to a wildcard (`*.my-network.localhost`) so sub-sites route to the
+container; `*.localhost` already resolves to `127.0.0.1`, so no `/etc/hosts` edits
+are needed. Network admin lives at `…/wp-admin/network/`.
+
+### WordPress VIP (mu-plugins)
+
+WPVIP sites expect the VIP Go mu-plugins under `wp-content/mu-plugins`. Pass
+`--vip` to `start` and the tool clones
+[`vip-go-mu-plugins-built`](https://github.com/Automattic/vip-go-mu-plugins-built)
+(shallow) and mounts it into the container at `wp-content/mu-plugins`:
+
+```bash
+42wp start my-vip-site --vip
+```
+
+The clone lives in the project's data dir (`~/.42wp/projects/<name>/mu-plugins`),
+so it never touches your repo, and re-running `start` fast-forwards it. Regular
+(non-VIP) projects are unaffected.
+
+`--vip` also mounts a small **dev-helper mu-plugin** (`00-42wp-dev.php`) that loads
+the WordPress admin media includes in admin/REST/CLI contexts. This fixes
+"Call to undefined function `media_handle_sideload()`"-style errors from plugins
+like FakerPress, which the VIP environment triggers by loading `file.php` early.
+It's mounted from the data dir, so your repo and the cloned VIP suite stay clean.
+
+### Example
+
+```bash
+cd ~/code/my-theme
+42wp global start
+42wp start my-theme
+# → http://my-theme.localhost  (admin / password at /wp-admin)
+42wp wp my-theme plugin list
+42wp stop my-theme
+```
+
+Shared services once the global layer is up:
+
+| Service     | URL                          |
+| ----------- | ---------------------------- |
+| Traefik     | http://localhost:8080        |
+| phpMyAdmin  | http://db.42wp.localhost     |
+| Mailpit     | http://mail.42wp.localhost   |
+
+## How it works
+
+State lives under `~/.42wp` (override with `FORTYTWO_HOME`):
+
+```
+~/.42wp/
+  docker-compose.global.yml   # the global layer (created on first run)
+  mysql-data/                 # persisted MySQL data
+  projects/<project>/         # generated wp-config.php, Dockerfile, docker-compose.yml
+```
+
+`42wp start` generates an ephemeral `wp-config.php` (fetching real salts from
+api.wordpress.org, with a local fallback when offline), a `Dockerfile`, and a
+`docker-compose.yml`, then builds the container and runs a silent
+`wp core install`. The DB name is the project name with hyphens turned into
+underscores; a trailing `.suffix` (e.g. `.localhost`) is stripped.
+
+## Configuration
+
+| Env var         | Default        | Description                                   |
+| --------------- | -------------- | --------------------------------------------- |
+| `FORTYTWO_HOME`   | `~/.42wp`        | Where the global compose, DB data and projects live |
+| `FORTYTWO_WP_TAG` | `php8.4-apache`  | Default WordPress image tag for new projects (overridden by `--wp`) |
+| `FORTYTWO_LANG`   | auto (`LANG`)    | UI language: `en` or `pt`                   |
+| `NO_COLOR`        | unset            | Disable colored output                      |
+
+You can also pass `--lang en` / `--lang pt` before the command.
+
+## License
+
+MIT

package/bin/42wp.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+import { run } from '../src/cli.js';
+import { error } from '../src/lib/log.js';
+
+run(process.argv.slice(2)).catch((err) => {
+  // Top-level safety net: anything that bubbles up here is unexpected.
+  error(err && err.message ? err.message : String(err));
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@42wp/dev-env",
+  "version": "1.0.0",
+  "description": "42WP — a CLI to spin up disposable WordPress dev environments with Docker (Traefik + MySQL + per-project containers).",
+  "type": "module",
+  "bin": {
+    "42wp": "bin/42wp.js"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "engines": {
+    "node": ">=18.17"
+  },
+  "scripts": {
+    "test": "node --test",
+    "prepublishOnly": "node --test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/42wp/dev-env.git"
+  },
+  "bugs": {
+    "url": "https://github.com/42wp/dev-env/issues"
+  },
+  "homepage": "https://github.com/42wp/dev-env#readme",
+  "keywords": [
+    "wordpress",
+    "docker",
+    "cli",
+    "dev-environment",
+    "traefik",
+    "wp-cli",
+    "42wp"
+  ],
+  "author": "João Carvalho <joao@carvalho.cc>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/cli.js

@@ -0,0 +1,119 @@
+// Argument parsing and command dispatch — mirrors the `case "$1"` block in 42script.sh.
+// A leading --lang / --lang=<locale> overrides the UI language; it's consumed before
+// dispatch so it never leaks into WP-CLI arguments passed through `42wp wp`.
+
+import { setLocale, t } from './lib/i18n.js';
+import { plain, error } from './lib/log.js';
+import { start } from './commands/start.js';
+import { stop } from './commands/stop.js';
+import { wp } from './commands/wp.js';
+import { update } from './commands/update.js';
+import { rm } from './commands/rm.js';
+import { seed } from './commands/seed.js';
+import { startGlobal, stopGlobal } from './commands/global.js';
+
+function extractLang(argv) {
+  let lang;
+  while (argv.length && argv[0].startsWith('--lang')) {
+    const flag = argv.shift();
+    if (flag.includes('=')) lang = flag.slice(flag.indexOf('=') + 1);
+    else lang = argv.shift(); // value is the next token
+  }
+  return lang;
+}
+
+// Flags that take a value (--wp tag, --user bob, --pass secret). Anything else
+// (e.g. --vip) is a boolean. The `--key=value` form works for all of them.
+const VALUE_FLAGS = new Set(['wp', 'user', 'pass']);
+
+// Pull options out of an arg list, leaving positionals behind. Used by `start`
+// and `update`; NOT by `wp`, whose args pass through verbatim to WP-CLI.
+export function parseOpts(args) {
+  const opts = {};
+  const positionals = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a.startsWith('--')) {
+      const eq = a.indexOf('=');
+      if (eq !== -1) {
+        opts[a.slice(2, eq)] = a.slice(eq + 1);
+      } else {
+        const key = a.slice(2);
+        if (VALUE_FLAGS.has(key)) opts[key] = args[++i];
+        else opts[key] = true; // boolean flag
+      }
+    } else {
+      positionals.push(a);
+    }
+  }
+  return { opts, positionals };
+}
+
+function printUsage() {
+  plain(t('usage.line'));
+  plain('');
+  plain(t('usage.commands'));
+  plain(t('usage.start'));
+  plain(t('usage.update'));
+  plain(t('usage.stop'));
+  plain(t('usage.rm'));
+  plain(t('usage.seed'));
+  plain(t('usage.wp'));
+  plain(t('usage.globalStart'));
+  plain(t('usage.globalStop'));
+}
+
+export async function run(rawArgs) {
+  const argv = [...rawArgs];
+  const lang = extractLang(argv);
+  setLocale(lang);
+
+  const command = argv[0];
+
+  switch (command) {
+    case 'start': {
+      const { opts, positionals } = parseOpts(argv.slice(1));
+      await start(positionals[0], opts);
+      break;
+    }
+
+    case 'update': {
+      const { opts, positionals } = parseOpts(argv.slice(1));
+      await update(positionals[0], opts);
+      break;
+    }
+
+    case 'stop':
+      await stop(argv[1]);
+      break;
+
+    case 'rm': {
+      const { opts, positionals } = parseOpts(argv.slice(1));
+      await rm(positionals[0], opts);
+      break;
+    }
+
+    case 'seed': {
+      const { opts, positionals } = parseOpts(argv.slice(1));
+      await seed(positionals[0], opts, positionals[1]);
+      break;
+    }
+
+    case 'wp':
+      await wp(argv[1], argv.slice(2));
+      break;
+
+    case 'global':
+      if (argv[1] === 'start') await startGlobal();
+      else if (argv[1] === 'stop') await stopGlobal();
+      else {
+        error(t('global.invalid'));
+        process.exitCode = 1;
+      }
+      break;
+
+    default:
+      printUsage();
+      process.exitCode = 1;
+  }
+}

package/src/commands/global.js

@@ -0,0 +1,62 @@
+// `42wp global start|stop` and the shared global-layer bootstrap used by `start`.
+// The global layer is Traefik + MySQL + phpMyAdmin + Mailpit on the 42wp_network.
+
+import {
+  dockerIsRunning,
+  composeCapture,
+  compose,
+  dockerExecCapture,
+} from '../lib/docker.js';
+import { ensureGlobalCompose } from '../lib/render.js';
+import { globalComposePath } from '../lib/paths.js';
+import { pollUntil } from '../lib/wait.js';
+import { step, error } from '../lib/log.js';
+import { t } from '../lib/i18n.js';
+
+// Exit early with a clear message if the Docker daemon isn't reachable.
+export async function ensureDockerRunning() {
+  if (!(await dockerIsRunning())) {
+    error(t('docker.notRunning'));
+    process.exitCode = 1;
+    return false;
+  }
+  return true;
+}
+
+async function mysqlReady() {
+  const { code } = await dockerExecCapture('42wp_mysql', [
+    'mysqladmin',
+    'ping',
+    '-uroot',
+    '-proot',
+    '--silent',
+  ]);
+  return code === 0;
+}
+
+// Bring the global layer up if it isn't already running, then wait for MySQL.
+// Replaces the bash `check_global_layer` (which used a fixed `sleep 10`).
+export async function checkGlobalLayer() {
+  const file = await ensureGlobalCompose();
+  const { stdout } = await composeCapture(['-f', file, 'ps', '-q']);
+  if (stdout.length === 0) {
+    step(t('global.starting'));
+    await compose(['-f', file, 'up', '-d']);
+    step(t('global.waitingMysql'));
+    await pollUntil(mysqlReady, { label: 'MySQL', timeout: 90000 });
+  }
+}
+
+export async function startGlobal() {
+  if (!(await ensureDockerRunning())) return;
+  const file = await ensureGlobalCompose();
+  step(t('global.starting'));
+  await compose(['-f', file, 'up', '-d']);
+}
+
+export async function stopGlobal() {
+  if (!(await ensureDockerRunning())) return;
+  const file = globalComposePath();
+  step(t('global.stopping'));
+  await compose(['-f', file, 'down']);
+}

package/src/commands/rm.js

@@ -0,0 +1,82 @@
+// `42wp rm <project> [--yes]` — remove a site from the dev env.
+//
+// Removes the project's containers + locally-built image, drops its database, and
+// deletes the generated project dir (~/.42wp/projects/<name>/, including any cloned
+// VIP mu-plugins). It does NOT touch your repository: wp-content is a bind mount of
+// your working directory, which `docker compose down` leaves untouched.
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { normalizeName, validateName, dbName } from '../lib/naming.js';
+import { projectDir } from '../lib/paths.js';
+import { compose, dockerExec, containerIsRunning } from '../lib/docker.js';
+import { confirm } from '../lib/prompt.js';
+import { step, success, plain, error } from '../lib/log.js';
+import { t } from '../lib/i18n.js';
+import { ensureDockerRunning } from './global.js';
+
+export async function rm(rawName, opts = {}) {
+  if (!rawName) {
+    error(t('rm.needName'));
+    process.exitCode = 1;
+    return;
+  }
+
+  const name = normalizeName(rawName);
+  validateName(name);
+  const db = dbName(name);
+  const envDir = projectDir(name);
+
+  // Must be a known project.
+  try {
+    await fs.access(envDir);
+  } catch {
+    error(t('rm.notFound', { name, dir: envDir }));
+    process.exitCode = 1;
+    return;
+  }
+
+  // Confirm unless --yes/--force. In a non-interactive shell we refuse rather
+  // than guess.
+  const skip = opts.yes || opts.force;
+  if (!skip) {
+    if (!process.stdin.isTTY) {
+      error(t('rm.needYes'));
+      process.exitCode = 1;
+      return;
+    }
+    const ok = await confirm(t('rm.confirm', { name }));
+    if (!ok) {
+      plain(t('rm.cancelled'));
+      return;
+    }
+  }
+
+  if (!(await ensureDockerRunning())) return;
+
+  // 1. Stop & remove containers + the image built for this project.
+  step(t('rm.removingContainers', { name }));
+  await compose(['down', '--rmi', 'local', '--remove-orphans'], { cwd: envDir });
+
+  // 2. Drop the database (only possible while the global MySQL is up).
+  if (await containerIsRunning('42wp_mysql')) {
+    step(t('rm.droppingDb', { db }));
+    await dockerExec('42wp_mysql', [
+      'mysql',
+      '-uroot',
+      '-proot',
+      '-e',
+      `DROP DATABASE IF EXISTS \`${db}\`;`,
+    ]);
+  } else {
+    step(t('rm.mysqlDown', { db }));
+  }
+
+  // 3. Delete the generated project dir (config, Dockerfile, compose, cloned
+  // mu-plugins). The repo bind-mounted as wp-content is never inside here.
+  step(t('rm.removingData', { dir: envDir }));
+  await fs.rm(envDir, { recursive: true, force: true });
+
+  success(t('rm.done', { name }));
+}

package/src/commands/seed.js

@@ -0,0 +1,42 @@
+// `42wp seed <project> [<count>] [--demo-content=<n>]` — generate demo content in
+// an already-running project, without recreating the container. Always creates the
+// requested number of posts (default 200).
+
+import { normalizeName, validateName, dbName, containerName } from '../lib/naming.js';
+import { containerIsRunning } from '../lib/docker.js';
+import { runSeeder } from '../lib/seeder.js';
+import { resolveDemoCount, DEFAULT_DEMO_COUNT } from '../lib/config.js';
+import { step, error } from '../lib/log.js';
+import { t } from '../lib/i18n.js';
+import { ensureDockerRunning } from './global.js';
+
+export async function seed(rawName, opts = {}, countArg) {
+  if (!rawName) {
+    error(t('seed.needName'));
+    process.exitCode = 1;
+    return;
+  }
+
+  const name = normalizeName(rawName);
+  validateName(name);
+  const container = containerName(dbName(name));
+
+  if (!(await ensureDockerRunning())) return;
+
+  if (!(await containerIsRunning(container))) {
+    error(t('seed.notRunning', { name }));
+    process.exitCode = 1;
+    return;
+  }
+
+  // Count from a positional arg or --demo-content=<n>; default 200.
+  const count = resolveDemoCount(countArg ?? opts['demo-content']) || DEFAULT_DEMO_COUNT;
+
+  step(t('start.demoGenerating', { count }));
+  try {
+    await runSeeder(container, count);
+  } catch {
+    error(t('seed.failed'));
+    process.exitCode = 1;
+  }
+}