@42wp/dev-env 1.0.1 → 1.0.4

package/README.md

@@ -25,6 +25,7 @@ This installs the `42wp` command globally.
 ## Usage
 
 ```bash
+42wp init [project]        # scaffold a .42wp-dev-env with this project's options
 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
@@ -37,6 +38,44 @@ This installs the `42wp` command globally.
 
 Run `42wp` with no arguments for the full command list.
 
+### Project config (`.42wp-dev-env`)
+
+Drop a `.42wp-dev-env` file in your project repo to save its `42wp start` options,
+so you (and your team) can just run `42wp start` with no flags. Scaffold one with
+`42wp init`:
+
+```bash
+42wp init mysite --subdomains --vip --locale pt_BR --theme my-theme --demo-content
+```
+
+That writes:
+
+```ini
+project_slug=mysite
+multisite=subdomain      # false | subdir | subdomain
+username=admin
+password=password
+locale=pt_BR
+default_theme=my-theme
+wpvip=true
+initial_content=200
+```
+
+`42wp start`, run in that directory, reads the file and applies it — and **CLI
+flags override** any value for a one-off run. With `project_slug` set you can run
+`42wp start` with no name. `42wp init` won't overwrite an existing file unless you
+pass `--force`.
+
+| Key | Effect |
+| --- | --- |
+| `project_slug`        | project name (so `42wp start` needs no argument) |
+| `multisite`           | `false`, `subdir` or `subdomain` |
+| `username` / `password` | admin credentials (plaintext — local dev only) |
+| `locale`              | WordPress site language, e.g. `pt_BR` (`pt-br` is normalized) |
+| `default_theme`       | theme to `wp theme activate` after install |
+| `wpvip`               | clone + mount the VIP mu-plugins |
+| `initial_content`     | `true` (200 posts) or a number |
+
 ### WordPress version
 
 By default projects are built on **`wordpress:php8.4-apache`** (newest WordPress,
@@ -93,6 +132,21 @@ posts (it doesn't skip when posts already exist), and a failure never aborts
 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.
 
+When the project ships the **42-framework** (detected by `client-mu-plugins/42-framework`
+or a `composer.json` that requires `42wp/wp-mu-plugins`), the seeder additionally
+configures — **once, idempotently** — a fuller site:
+
+- the `/%category%/%postname%/` permalink structure
+- a `42wp_homepage` post set as the static front page (falls back to a regular page
+  if the type isn't registered)
+- 4 category-driven menus — Header Primário / Secundário and Footer Primário / Social
+  (with a nested footer and YouTube/X/Instagram links) — assigned to the theme's
+  registered menu locations
+
+Re-running (or `42wp seed`) reuses the existing homepage and menus instead of
+duplicating them; only posts keep appending. On a plain WordPress site these extra
+steps are skipped and only the content above is seeded.
+
 To add demo content to an **already-running** project without recreating it, use
 `seed`:
 
@@ -111,6 +165,21 @@ project on `start`:
 42wp start my-theme --user joao --pass s3cr3t
 ```
 
+### Site language
+
+New sites install in English (`en_US`) by default. Pick a WordPress locale with
+`--locale`; the language pack is downloaded and activated automatically:
+
+```bash
+42wp start my-site --locale pt_BR      # Brazilian Portuguese
+42wp start my-site --locale es_ES      # Spanish (Spain)
+```
+
+Set a default for every project with the `FORTYTWO_WP_LOCALE` env var. This is the
+**site** language — distinct from `--lang`, which controls the `42wp` CLI's own
+messages (`en`/`pt`). The pack is downloaded into `wp-content/languages`; if the
+download fails (e.g. offline), the site stays in English and `start` continues.
+
 ### Multisite
 
 Start a site as a WordPress network with `--multisite` (subdirectory) or add
@@ -177,7 +246,7 @@ 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
+  projects/<project>/         # generated wp-config.php, Dockerfile, docker-compose.yml, meta.json
 ```
 
 `42wp start` generates an ephemeral `wp-config.php` (fetching real salts from
@@ -186,6 +255,15 @@ api.wordpress.org, with a local fallback when offline), a `Dockerfile`, and a
 `wp core install`. The DB name is the project name with hyphens turned into
 underscores; a trailing `.suffix` (e.g. `.localhost`) is stripped.
 
+**Where a project is bound.** `42wp start` mounts the directory you run it from as
+`wp-content`, so it first checks that directory looks like one — it must contain
+`plugins/` and `themes/`, otherwise `start` refuses (rather than building a broken
+site). Pass `--force` to override (e.g. bootstrapping a brand-new, empty project).
+The chosen directory is recorded in the project's `meta.json`, and later `start`s
+reuse it — so re-running from a different folder can't silently re-point the
+container. Run `42wp start <name> --rebind` from a new directory to move the binding
+there on purpose.
+
 The generated `wp-config.php` always defines `WP_ENVIRONMENT_TYPE` as `local`, so
 `wp_get_environment_type()` reports `local` (not the WordPress default of
 `production`) — code and plugins that branch on the environment behave as they
@@ -199,7 +277,8 @@ should in dev. The constant is set before mu-plugins load, so it holds even unde
 | --------------- | -------------- | --------------------------------------------- |
 | `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`                   |
+| `FORTYTWO_WP_LOCALE` | unset (`en_US`) | Default WordPress **site** language for new projects (overridden by `--locale`) |
+| `FORTYTWO_LANG`   | auto (`LANG`)    | CLI UI language: `en` or `pt`               |
 | `NO_COLOR`        | unset            | Disable colored output                      |
 
 You can also pass `--lang en` / `--lang pt` before the command.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@42wp/dev-env",
-  "version": "1.0.1",
+  "version": "1.0.4",
   "description": "42WP — a CLI to spin up disposable WordPress dev environments with Docker (Traefik + MySQL + per-project containers).",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -10,6 +10,7 @@ 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 { init } from './commands/init.js';
 import { startGlobal, stopGlobal } from './commands/global.js';
 
 function extractLang(argv) {
@@ -24,7 +25,7 @@ function extractLang(argv) {
 
 // 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']);
+const VALUE_FLAGS = new Set(['wp', 'user', 'pass', 'locale', 'theme']);
 
 // 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.
@@ -53,6 +54,7 @@ function printUsage() {
   plain(t('usage.line'));
   plain('');
   plain(t('usage.commands'));
+  plain(t('usage.init'));
   plain(t('usage.start'));
   plain(t('usage.update'));
   plain(t('usage.stop'));
@@ -99,6 +101,12 @@ export async function run(rawArgs) {
       break;
     }
 
+    case 'init': {
+      const { opts, positionals } = parseOpts(argv.slice(1));
+      await init(positionals[0], opts);
+      break;
+    }
+
     case 'wp':
       await wp(argv[1], argv.slice(2));
       break;

package/src/commands/init.js

@@ -0,0 +1,66 @@
+// `42wp init [project] [flags]` — scaffold a .42wp-dev-env file in the current
+// directory from the given flags (or sensible defaults), so `42wp start` can read
+// the project's options next time. Refuses to overwrite unless --force / --yes.
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { normalizeName } from '../lib/naming.js';
+import { PROJECT_CONFIG_FILE } from '../lib/projectConfig.js';
+import {
+  resolveLocale,
+  resolveDemoCount,
+  DEFAULT_ADMIN_USER,
+  DEFAULT_ADMIN_PASS,
+} from '../lib/config.js';
+import { success, error, plain } from '../lib/log.js';
+import { t } from '../lib/i18n.js';
+
+export async function init(rawName, opts = {}) {
+  const dir = process.cwd();
+  const file = path.join(dir, PROJECT_CONFIG_FILE);
+
+  // Don't clobber an existing file unless explicitly forced.
+  try {
+    await fs.access(file);
+    if (!opts.force && !opts.yes) {
+      error(t('init.exists', { file: PROJECT_CONFIG_FILE }));
+      process.exitCode = 1;
+      return;
+    }
+  } catch {
+    // no existing file — good to write
+  }
+
+  const slug = normalizeName(rawName || opts.project_slug || path.basename(dir));
+  const subdomains = !!opts.subdomains;
+  const multisiteMode = subdomains ? 'subdomain' : opts.multisite ? 'subdir' : 'false';
+  const user = opts.user || DEFAULT_ADMIN_USER;
+  const pass = opts.pass || DEFAULT_ADMIN_PASS;
+  const locale = resolveLocale(opts.locale) || 'en_US';
+  const theme = opts.theme || '';
+  const vip = !!opts.vip;
+  const demo = resolveDemoCount(opts['demo-content']); // null | number
+  const initialContent = demo ? String(demo) : 'false';
+
+  const content =
+    [
+      '# 42wp dev environment — project config (.42wp-dev-env)',
+      '# Read by `42wp start` in this directory. CLI flags override these values.',
+      '# multisite: false | subdir | subdomain   ·   booleans: true | false',
+      '# locale uses the WordPress format, e.g. pt_BR, es_ES',
+      '',
+      `project_slug=${slug}`,
+      `multisite=${multisiteMode}`,
+      `username=${user}`,
+      `password=${pass}`,
+      `locale=${locale}`,
+      `default_theme=${theme}`,
+      `wpvip=${vip}`,
+      `initial_content=${initialContent}`,
+    ].join('\n') + '\n';
+
+  await fs.writeFile(file, content, 'utf8');
+  success(t('init.created', { file: PROJECT_CONFIG_FILE }));
+  plain(t('init.next'));
+}

package/src/commands/start.js

@@ -14,6 +14,15 @@ import {
   routerRule,
 } from '../lib/naming.js';
 import { projectDir } from '../lib/paths.js';
+import { readProjectConfig } from '../lib/projectConfig.js';
+import {
+  missingWpDirs,
+  pathExists,
+  readProjectMeta,
+  writeProjectMeta,
+  readComposeRepoDir,
+  REQUIRED_WP_DIRS,
+} from '../lib/projectState.js';
 import { renderTemplate, render, readTemplate } from '../lib/render.js';
 import { fetchSalts } from '../lib/salts.js';
 import { run, compose, dockerExec, dockerExecCapture } from '../lib/docker.js';
@@ -26,6 +35,7 @@ import {
   wpImage,
   multisiteConfig,
   resolveDemoCount,
+  resolveLocale,
   DEFAULT_ADMIN_USER,
   DEFAULT_ADMIN_PASS,
   VIP_MU_PLUGINS_REPO,
@@ -50,34 +60,87 @@ async function ensureVipMuPlugins(envDir) {
 }
 
 export async function start(rawName, opts = {}) {
-  if (!rawName) {
+  // The directory the user is sitting in may carry a .42wp-dev-env with saved
+  // options. CLI flags still take precedence over it.
+  const cwd = process.cwd();
+  const fileOpts = readProjectConfig(cwd);
+  if (Object.keys(fileOpts).length > 0) {
+    opts = { ...fileOpts, ...opts };
+    step(t('start.usingConfig'));
+  }
+
+  const projectName = rawName || opts.project_slug;
+  if (!projectName) {
     error(t('start.needName'));
     process.exitCode = 1;
     return;
   }
 
-  // The repo the user is sitting in becomes the container's wp-content.
-  const repoDir = process.cwd();
-
-  const name = normalizeName(rawName);
+  const name = normalizeName(projectName);
   validateName(name);
 
   const dom = domain(name);
   const db = dbName(name);
   const container = containerName(db);
   const envDir = projectDir(name);
+
+  // Resolve which host directory is mounted as wp-content. The FIRST start binds
+  // to the current directory and records it in meta.json; later starts reuse that
+  // path, so re-running from another folder can't silently re-point the mount.
+  // --rebind moves the binding to the current directory.
+  const meta = await readProjectMeta(envDir);
+  // Recorded binding, or (for projects created before meta.json) recover it from
+  // the existing compose so an upgrade doesn't lose the original directory.
+  const boundDir = meta.repoDir || (await readComposeRepoDir(envDir));
+  let repoDir = cwd;
+  if (boundDir && !opts.rebind) {
+    if (await pathExists(boundDir)) {
+      repoDir = boundDir;
+      if (path.resolve(repoDir) !== path.resolve(cwd)) {
+        step(t('start.boundTo', { dir: repoDir }));
+      }
+    } else {
+      // The recorded directory is gone — fall back to the current one.
+      step(t('start.boundMissing', { dir: boundDir }));
+      repoDir = cwd;
+    }
+  } else if (opts.rebind && boundDir && path.resolve(boundDir) !== path.resolve(cwd)) {
+    step(t('start.rebound', { dir: cwd }));
+  }
+
+  // Guard: refuse to mount a directory that isn't a wp-content root (missing the
+  // minimal plugins/ + themes/), which would produce a broken WordPress install.
+  // --force overrides (e.g. bootstrapping a brand-new, empty project).
+  if (!opts.force) {
+    const missing = await missingWpDirs(repoDir);
+    if (missing.length) {
+      error(
+        t('start.notWpContent', {
+          dir: repoDir,
+          missing: missing.map((d) => `${d}/`).join(', '),
+          required: REQUIRED_WP_DIRS.map((d) => `${d}/`).join(', '),
+        }),
+      );
+      process.exitCode = 1;
+      return;
+    }
+  }
   const adminUser = opts.user || DEFAULT_ADMIN_USER;
   const adminPass = opts.pass || DEFAULT_ADMIN_PASS;
   // --subdomains implies multisite; without it, --multisite is subdirectory mode.
   const subdomains = !!opts.subdomains;
   const multisite = !!opts.multisite || subdomains;
   const demoCount = resolveDemoCount(opts['demo-content']); // null when not requested
+  const locale = resolveLocale(opts.locale); // '' = WordPress default (en_US)
+  const theme = opts.theme || ''; // activate this theme after install (if present)
 
   if (!(await ensureDockerRunning())) return;
   await checkGlobalLayer();
 
   step(t('start.preparing', { domain: dom }));
   await fs.mkdir(envDir, { recursive: true });
+  // Record (or update, on --rebind) the directory bound as wp-content.
+  await writeProjectMeta(envDir, { repoDir });
 
   // 1. Database on the global MySQL.
   step(t('start.creatingDb', { db }));
@@ -175,12 +238,30 @@ export async function start(rawName, opts = {}) {
     `--admin_user=${adminUser}`,
     `--admin_password=${adminPass}`,
     `--admin_email=${ADMIN_EMAIL}`,
+    ...(locale ? [`--locale=${locale}`] : []),
     '--skip-email',
     '--skip-plugins',
     '--skip-themes',
     '--allow-root',
   ]);
 
+  // 7a. Install and activate the requested site language (downloads the .mo pack
+  //     into wp-content/languages). Non-fatal — a failure (e.g. offline) leaves
+  //     the site in English rather than aborting the whole start.
+  if (locale && locale !== 'en_US') {
+    step(t('start.installingLang', { locale }));
+    const lang = await dockerExecCapture(container, [
+      'wp',
+      'language',
+      'core',
+      'install',
+      locale,
+      '--activate',
+      '--allow-root',
+    ]);
+    if (lang.code !== 0) step(t('start.langFailed', { locale }));
+  }
+
   // 7b. Multisite: create the network tables while WP is still single-site
   //     (--skip-config: we manage wp-config ourselves), then enable the MULTISITE
   //     constants. Order matters — the constants must come AFTER the tables exist.
@@ -202,6 +283,15 @@ export async function start(rawName, opts = {}) {
     await writeWpConfig(multisiteConfig(dom, { subdomains }));
   }
 
+  // 7c. Activate the project theme (from .42wp-dev-env `default_theme=` or --theme)
+  //     BEFORE seeding demo content, so its menu locations/features are registered
+  //     when the seeder runs. Non-fatal — a missing theme just logs a warning.
+  if (theme) {
+    step(t('start.activatingTheme', { theme }));
+    const act = await dockerExecCapture(container, ['wp', 'theme', 'activate', theme, '--allow-root']);
+    if (act.code !== 0) step(t('start.themeFailed', { theme }));
+  }
+
   // 8. Pretty permalinks.
   step(t('start.permalinks'));
   await dockerExec(container, [
@@ -229,6 +319,8 @@ export async function start(rawName, opts = {}) {
   plain(colors.green(t('start.admin', { url })));
   plain(colors.green(t('start.user', { user: adminUser })));
   plain(colors.green(t('start.pass', { pass: adminPass })));
+  if (locale) plain(colors.green(t('start.locale', { locale })));
+  if (theme) plain(colors.green(t('start.theme', { theme })));
   if (multisite) {
     const mode = subdomains ? 'subdomain' : 'subdirectory';
     plain(colors.green(t('start.multisite', { mode, url })));

package/src/lib/config.js

@@ -34,6 +34,26 @@ export function resolveWpTag(override) {
   return override || process.env.FORTYTWO_WP_TAG || DEFAULT_WP_TAG;
 }
 
+// WordPress site language (locale). Empty means the WordPress default (en_US) — no
+// language pack is downloaded. Set per project with --locale (e.g. pt_BR, es_ES),
+// or globally with FORTYTWO_WP_LOCALE. Distinct from --lang, which is the CLI's own
+// UI language.
+export const DEFAULT_WP_LOCALE = '';
+
+// Normalize a locale to the WordPress format: `pt-br` / `pt_br` -> `pt_BR`.
+// Values that don't fit the simple ll[_-]RR shape (e.g. `en_US`, `es_419`,
+// `de_DE_formal`) pass through unchanged.
+export function normalizeLocale(loc) {
+  if (!loc) return '';
+  const s = String(loc).trim();
+  const m = /^([a-z]{2,3})[-_]([a-z]{2})$/i.exec(s);
+  return m ? `${m[1].toLowerCase()}_${m[2].toUpperCase()}` : s;
+}
+
+export function resolveLocale(override) {
+  return normalizeLocale(override || process.env.FORTYTWO_WP_LOCALE || DEFAULT_WP_LOCALE);
+}
+
 // Full image reference for display/logging.
 export function wpImage(tag) {
   return `wordpress:${tag}`;

package/src/lib/docker.js

@@ -4,6 +4,25 @@
 
 import { spawn } from 'node:child_process';
 
+// Format a command + args for human-readable error/log lines. Args that contain
+// spaces or shell metacharacters are POSIX-single-quoted so the line is
+// unambiguous and copy-pasteable. This is DISPLAY ONLY — real execution always
+// passes args as an array to spawn() (no shell), so nothing here affects how
+// commands actually run.
+export function formatCommand(cmd, args = []) {
+  return [cmd, ...args].map(quoteForDisplay).join(' ');
+}
+
+function quoteForDisplay(arg) {
+  const s = String(arg);
+  if (s === '') return "''";
+  // Bare word when it's only safe characters (letters, digits and common URL/flag
+  // punctuation) — e.g. --url=http://base.localhost stays unquoted.
+  if (/^[A-Za-z0-9_@%+=:,.\/-]+$/.test(s)) return s;
+  // Otherwise single-quote, escaping any embedded single quotes.
+  return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+
 // Run a command, streaming its stdio to the user. Resolves on exit 0, rejects otherwise.
 export function run(cmd, args, opts = {}) {
   return new Promise((resolve, reject) => {
@@ -11,7 +30,7 @@ export function run(cmd, args, opts = {}) {
     child.on('error', reject);
     child.on('close', (code) => {
       if (code === 0) resolve();
-      else reject(new Error(`${cmd} ${args.join(' ')} exited with code ${code}`));
+      else reject(new Error(`${formatCommand(cmd, args)} exited with code ${code}`));
     });
   });
 }
@@ -24,7 +43,7 @@ export function runWithInput(cmd, args, input, opts = {}) {
     child.on('error', reject);
     child.on('close', (code) => {
       if (code === 0) resolve();
-      else reject(new Error(`${cmd} ${args.join(' ')} exited with code ${code}`));
+      else reject(new Error(`${formatCommand(cmd, args)} exited with code ${code}`));
     });
     child.stdin.write(input);
     child.stdin.end();

package/src/lib/naming.js

@@ -6,7 +6,7 @@
 
 import { t } from './i18n.js';
 
-// Remove the shortest trailing ".something", e.g. "jovempan.localhost" -> "jovempan".
+// Remove the shortest trailing ".something", e.g. "mysite.localhost" -> "mysite".
 export function normalizeName(raw) {
   return String(raw ?? '').replace(/\.[^.]*$/, '');
 }

package/src/lib/projectConfig.js

@@ -0,0 +1,91 @@
+// Reads an optional per-project config file (.42wp-dev-env) from the directory a
+// command is run in, so a repo can carry its own `42wp start` defaults. Values are
+// returned shaped like the parsed CLI opts, so a command can merge them as
+// defaults UNDER the real flags (a CLI flag always wins over the file).
+//
+// Format: `key=value`, one per line. `#` comments and blank lines are ignored;
+// surrounding quotes on a value are stripped.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const PROJECT_CONFIG_FILE = '.42wp-dev-env';
+
+// File key -> opts key. Both the documented names and the CLI-flag names are
+// accepted so the file stays forgiving. `project_slug` becomes the project name.
+// `multisite` is handled separately (its value picks subdir/subdomain).
+const KEY_MAP = {
+  project_slug: 'project_slug',
+  slug: 'project_slug',
+  username: 'user',
+  user: 'user',
+  password: 'pass',
+  pass: 'pass',
+  locale: 'locale',
+  default_theme: 'theme',
+  theme: 'theme',
+  wpvip: 'vip',
+  vip: 'vip',
+  wp: 'wp',
+  initial_content: 'demo-content',
+  'demo-content': 'demo-content',
+};
+
+const BOOL_KEYS = new Set(['vip']);
+
+const isTrue = (v) => /^(1|true|yes|on)$/i.test(v);
+
+// Parse .42wp-dev-env from `dir`. Returns {} when the file is absent or unreadable.
+export function readProjectConfig(dir) {
+  let text;
+  try {
+    text = fs.readFileSync(path.join(dir, PROJECT_CONFIG_FILE), 'utf8');
+  } catch {
+    return {};
+  }
+
+  const out = {};
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) continue;
+    const eq = line.indexOf('=');
+    if (eq === -1) continue;
+
+    const rawKey = line.slice(0, eq).trim().toLowerCase();
+    let value = line.slice(eq + 1).trim();
+    // Strip an inline comment (" # ..."), unless the value is quoted. A '#' with no
+    // preceding whitespace is kept, so values like a password can contain it.
+    if (value[0] !== '"' && value[0] !== "'") {
+      value = value.replace(/\s+#.*$/, '').trim();
+    }
+    // Strip surrounding matching quotes.
+    value = value.replace(/^(['"])(.*)\1$/, '$2');
+
+    // multisite=subdir|subdomain (true == subdir; false/absent == single site).
+    if (rawKey === 'multisite') {
+      const v = value.toLowerCase();
+      if (/^(subdomain|subdomains)$/.test(v)) {
+        out.multisite = true;
+        out.subdomains = true;
+      } else if (/^(subdir|subdirectory|true|yes|1|on)$/.test(v)) {
+        out.multisite = true;
+        out.subdomains = false;
+      }
+      continue;
+    }
+
+    const key = KEY_MAP[rawKey];
+    if (!key) continue; // ignore unknown keys
+
+    if (BOOL_KEYS.has(key)) {
+      out[key] = isTrue(value);
+    } else if (key === 'demo-content') {
+      // true -> bare flag (default count); a number -> that count; false -> omit.
+      if (isTrue(value)) out[key] = true;
+      else if (/^\d+$/.test(value)) out[key] = value;
+    } else if (value !== '') {
+      out[key] = value;
+    }
+  }
+  return out;
+}

package/src/lib/projectState.js

@@ -0,0 +1,66 @@
+// Per-project runtime state kept in the generated project dir (~/.42wp/projects/<name>/):
+//   - meta.json remembers which host directory is bound as wp-content, so
+//     re-running `start` from another folder can't silently re-point the mount.
+//   - a guard that the directory about to be mounted really is a wp-content
+//     (has the minimal plugins/ and themes/ subdirectories).
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const META_FILE = 'meta.json';
+
+// Sub-directories that must exist for a folder to count as a wp-content root.
+export const REQUIRED_WP_DIRS = ['plugins', 'themes'];
+
+// Returns the required wp-content subdirs that are missing from `dir` (empty means
+// the directory looks like a valid wp-content).
+export async function missingWpDirs(dir) {
+  const missing = [];
+  for (const sub of REQUIRED_WP_DIRS) {
+    try {
+      const st = await fs.stat(path.join(dir, sub));
+      if (!st.isDirectory()) missing.push(sub);
+    } catch {
+      missing.push(sub);
+    }
+  }
+  return missing;
+}
+
+export async function pathExists(p) {
+  try {
+    await fs.stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Read the project's meta.json (returns {} when absent/unreadable).
+export async function readProjectMeta(envDir) {
+  try {
+    return JSON.parse(await fs.readFile(path.join(envDir, META_FILE), 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+// Recover the wp-content bind-mount source from an existing docker-compose.yml,
+// for projects created before meta.json existed. Returns '' when not found.
+export async function readComposeRepoDir(envDir) {
+  try {
+    const yml = await fs.readFile(path.join(envDir, 'docker-compose.yml'), 'utf8');
+    const m = yml.match(/^\s*-\s*(.+):\/var\/www\/html\/wp-content\s*$/m);
+    return m ? m[1].trim() : '';
+  } catch {
+    return '';
+  }
+}
+
+// Persist the project's meta.json (merging over any existing fields).
+export async function writeProjectMeta(envDir, data) {
+  const current = await readProjectMeta(envDir);
+  const next = { ...current, ...data };
+  await fs.writeFile(path.join(envDir, META_FILE), `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+  return next;
+}

package/src/locales/en.js

@@ -13,7 +13,13 @@ export default {
   'global.invalid': "Invalid global command. Use 'start' or 'stop'.",
 
   // start
-  'start.needName': 'You must provide a project name. e.g.: 42wp start jovempan',
+  'start.needName': 'You must provide a project name (or set project_slug in .42wp-dev-env). e.g.: 42wp start mysite',
+  'start.usingConfig': 'Using options from .42wp-dev-env (CLI flags override).',
+  'start.notWpContent':
+    '${dir} is not a wp-content directory (missing ${missing}). Run 42wp start from your project root (it needs ${required}), or pass --force to override.',
+  'start.boundTo': 'Project is bound to ${dir}; keeping it. Use --rebind to point it at the current directory.',
+  'start.boundMissing': 'Bound directory ${dir} no longer exists — binding to the current directory.',
+  'start.rebound': 'Rebinding project to ${dir}.',
   'start.preparing': 'Preparing environment for ${domain}...',
   'start.creatingDb': 'Creating database: ${db}',
   'start.genConfig': 'Generating ephemeral wp-config.php...',
@@ -25,6 +31,10 @@ export default {
   'start.upping': 'Starting project containers...',
   'start.waitingWp': 'Waiting for the WordPress container to respond...',
   'start.installing': 'Running silent WordPress install...',
+  'start.installingLang': 'Installing WordPress language pack (${locale})...',
+  'start.langFailed': 'Could not install the ${locale} language pack (continuing in English).',
+  'start.activatingTheme': 'Activating theme (${theme})...',
+  'start.themeFailed': 'Could not activate the "${theme}" theme (is it in the repo?).',
   'start.enablingMultisite': 'Enabling multisite (network tables + wp-config constants)...',
   'start.permalinks': 'Configuring permalinks...',
   'start.demoGenerating': 'Seeding ${count} demo posts (authors, tags, categories, images)...',
@@ -34,17 +44,24 @@ export default {
   'start.admin': 'Admin:    ${url}/wp-admin',
   'start.user': 'User:     ${user}',
   'start.pass': 'Password: ${pass}',
+  'start.locale': 'Language: ${locale}',
+  'start.theme': 'Theme:    ${theme}',
   'start.multisite': 'Multisite: ${mode}. Network admin: ${url}/wp-admin/network/',
 
+  // init
+  'init.exists': '${file} already exists here. Re-run with --force to overwrite.',
+  'init.created': 'Created ${file}. Edit it, then run 42wp start.',
+  'init.next': 'Tip: with project_slug set, you can run 42wp start with no name.',
+
   // update
-  'update.needName': 'Tell me which project to update. e.g.: 42wp update jovempan',
+  'update.needName': 'Tell me which project to update. e.g.: 42wp update mysite',
   'update.notFound': "Project '${name}' not found at ${dir}. Run 42wp start ${name} first.",
   'update.rebuilding': 'Rebuilding ${name} on ${image}...',
   'update.updatingDb': 'Updating database schema (wp core update-db)...',
   'update.done': 'Updated! ${name} is now on WordPress ${version}.',
 
   // rm
-  'rm.needName': 'Tell me which project to remove. e.g.: 42wp rm jovempan',
+  'rm.needName': 'Tell me which project to remove. e.g.: 42wp rm mysite',
   'rm.notFound': "Project '${name}' not found at ${dir}.",
   'rm.confirm':
     "Remove '${name}'? This deletes its container, image and database. Your repository is kept.",
@@ -57,17 +74,17 @@ export default {
   'rm.done': "Removed '${name}'. Your repository was left untouched.",
 
   // seed
-  'seed.needName': 'Tell me which project to seed. e.g.: 42wp seed jovempan',
+  'seed.needName': 'Tell me which project to seed. e.g.: 42wp seed mysite',
   'seed.notRunning': "Project '${name}' is not running. Start it first with 42wp start ${name}.",
   'seed.failed': 'Demo content generation failed.',
 
   // stop
-  'stop.needName': 'Tell me which project to stop. e.g.: 42wp stop jovempan',
+  'stop.needName': 'Tell me which project to stop. e.g.: 42wp stop mysite',
   'stop.stopping': 'Stopping the ${name} environment...',
   'stop.notFound': 'Environment for ${name} not found at ${dir}.',
 
   // wp proxy
-  'wp.needArgs': 'Provide the project and command. e.g.: 42wp wp jovempan plugin list',
+  'wp.needArgs': 'Provide the project and command. e.g.: 42wp wp mysite plugin list',
   'wp.notRunning': 'Container ${container} is not running.',
 
   // validation
@@ -77,6 +94,7 @@ export default {
   // usage
   'usage.line': 'Usage: 42wp <command> [project] [arguments]',
   'usage.commands': 'Commands:',
+  'usage.init': '  init [project]     Scaffold a .42wp-dev-env in the current directory.',
   'usage.start': '  start <project>    Start the environment using \'.localhost\'.',
   'usage.update': '  update <project>   Update an existing project to a newer WordPress image.',
   'usage.stop': '  stop <project>     Stop the project containers.',

package/src/locales/pt.js

@@ -13,7 +13,13 @@ export default {
   'global.invalid': "Comando global inválido. Use 'start' ou 'stop'.",
 
   // start
-  'start.needName': 'Você precisa informar o nome do projeto. Ex: 42wp start jovempan',
+  'start.needName': 'Você precisa informar o nome do projeto (ou definir project_slug no .42wp-dev-env). Ex: 42wp start mysite',
+  'start.usingConfig': 'Usando opções do .42wp-dev-env (flags da CLI têm prioridade).',
+  'start.notWpContent':
+    '${dir} não é um diretório wp-content (falta ${missing}). Rode 42wp start na raiz do projeto (precisa de ${required}), ou use --force para ignorar.',
+  'start.boundTo': 'O projeto está vinculado a ${dir}; mantendo. Use --rebind para apontar para o diretório atual.',
+  'start.boundMissing': 'O diretório vinculado ${dir} não existe mais — vinculando ao diretório atual.',
+  'start.rebound': 'Revinculando o projeto para ${dir}.',
   'start.preparing': 'Preparando ambiente para ${domain}...',
   'start.creatingDb': 'Criando banco de dados: ${db}',
   'start.genConfig': 'Gerando wp-config.php efêmero...',
@@ -25,6 +31,10 @@ export default {
   'start.upping': 'Subindo containers do projeto...',
   'start.waitingWp': 'Aguardando o container WP responder...',
   'start.installing': 'Executando instalação silenciosa do WordPress...',
+  'start.installingLang': 'Instalando o pacote de idioma do WordPress (${locale})...',
+  'start.langFailed': 'Não foi possível instalar o pacote de idioma ${locale} (continuando em inglês).',
+  'start.activatingTheme': 'Ativando o tema (${theme})...',
+  'start.themeFailed': 'Não foi possível ativar o tema "${theme}" (ele está no repositório?).',
   'start.enablingMultisite': 'Habilitando multisite (tabelas de rede + constantes no wp-config)...',
   'start.permalinks': 'Configurando Permalinks...',
   'start.demoGenerating': 'Gerando ${count} posts de demonstração (autores, tags, categorias, imagens)...',
@@ -34,17 +44,24 @@ export default {
   'start.admin': 'Admin:    ${url}/wp-admin',
   'start.user': 'Usuário:  ${user}',
   'start.pass': 'Senha:    ${pass}',
+  'start.locale': 'Idioma:   ${locale}',
+  'start.theme': 'Tema:     ${theme}',
   'start.multisite': 'Multisite: ${mode}. Admin da rede: ${url}/wp-admin/network/',
 
+  // init
+  'init.exists': '${file} já existe aqui. Rode novamente com --force para sobrescrever.',
+  'init.created': 'Criado ${file}. Edite-o e rode 42wp start.',
+  'init.next': 'Dica: com project_slug definido, você pode rodar 42wp start sem o nome.',
+
   // update
-  'update.needName': 'Informe o projeto para atualizar. Ex: 42wp update jovempan',
+  'update.needName': 'Informe o projeto para atualizar. Ex: 42wp update mysite',
   'update.notFound': "Projeto '${name}' não encontrado em ${dir}. Rode 42wp start ${name} primeiro.",
   'update.rebuilding': 'Reconstruindo ${name} com ${image}...',
   'update.updatingDb': 'Atualizando o schema do banco (wp core update-db)...',
   'update.done': 'Atualizado! ${name} agora está no WordPress ${version}.',
 
   // rm
-  'rm.needName': 'Informe o projeto para remover. Ex: 42wp rm jovempan',
+  'rm.needName': 'Informe o projeto para remover. Ex: 42wp rm mysite',
   'rm.notFound': "Projeto '${name}' não encontrado em ${dir}.",
   'rm.confirm':
     "Remover '${name}'? Isso apaga o container, a imagem e o banco de dados. Seu repositório é mantido.",
@@ -57,17 +74,17 @@ export default {
   'rm.done': "Removido '${name}'. Seu repositório não foi tocado.",
 
   // seed
-  'seed.needName': 'Informe o projeto para popular. Ex: 42wp seed jovempan',
+  'seed.needName': 'Informe o projeto para popular. Ex: 42wp seed mysite',
   'seed.notRunning': "O projeto '${name}' não está rodando. Inicie com 42wp start ${name} primeiro.",
   'seed.failed': 'Falha ao gerar o conteúdo de demonstração.',
 
   // stop
-  'stop.needName': 'Informe o projeto para parar. Ex: 42wp stop jovempan',
+  'stop.needName': 'Informe o projeto para parar. Ex: 42wp stop mysite',
   'stop.stopping': 'Parando o ambiente ${name}...',
   'stop.notFound': 'Ambiente para ${name} não encontrado em ${dir}.',
 
   // proxy wp
-  'wp.needArgs': 'Informe o projeto e o comando. Ex: 42wp wp jovempan plugin list',
+  'wp.needArgs': 'Informe o projeto e o comando. Ex: 42wp wp mysite plugin list',
   'wp.notRunning': 'Container ${container} não está rodando.',
 
   // validação
@@ -77,6 +94,7 @@ export default {
   // uso
   'usage.line': 'Uso: 42wp <comando> [projeto] [argumentos]',
   'usage.commands': 'Comandos:',
+  'usage.init': '  init [projeto]     Cria um .42wp-dev-env no diretório atual.',
   'usage.start': "  start <projeto>    Inicia o ambiente usando '.localhost'.",
   'usage.update': '  update <projeto>   Atualiza um projeto existente para uma imagem mais recente do WordPress.',
   'usage.stop': '  stop <projeto>     Para os containers do projeto.',

package/src/templates/demo-seed.php

@@ -9,6 +9,15 @@
  *   - <count> posts: rich HTML content + plain-text excerpt + featured image,
  *     each linked to 1 category, 2-5 tags and 1-3 authors, with varied past dates.
  *
+ * When the 42-framework is part of the project (its files live under
+ * client-mu-plugins, or composer.json requires it) it also configures, once
+ * (idempotent):
+ *   - the `/%category%/%postname%/` permalink structure
+ *   - a `42wp_homepage` post set as the static front page
+ *   - 4 category-driven menus (header primary/secondary, footer primary/social)
+ *     assigned to the theme's registered locations
+ * On a plain WordPress site those steps are skipped and only content is seeded.
+ *
  * This file is managed by the dev environment; edits will be overwritten.
  */
 
@@ -199,4 +208,153 @@ for ( $i = 0; $i < $count; $i++ ) {
 	}
 }
 
-WP_CLI::success( sprintf( 'Created %d demo posts.', $created ) );
+WP_CLI::log( sprintf( 'Created %d demo posts.', $created ) );
+
+/* -------------------------------------------------------------------------- *
+ * 42-framework extras — permalinks, front page, menus
+ *
+ * Only applied when the 42-framework is part of the project: its files under
+ * client-mu-plugins/42-framework, or a composer.json that requires it
+ * (42wp/wp-mu-plugins). On a plain WordPress site these steps are skipped and
+ * only the content above is seeded.
+ * -------------------------------------------------------------------------- */
+
+$framework_active = is_dir( WP_CONTENT_DIR . '/client-mu-plugins/42-framework' );
+if ( ! $framework_active && is_readable( WP_CONTENT_DIR . '/composer.json' ) ) {
+	$composer         = (string) file_get_contents( WP_CONTENT_DIR . '/composer.json' );
+	$framework_active = ( false !== strpos( $composer, '42-framework' ) || false !== strpos( $composer, '42wp/wp-mu-plugins' ) );
+}
+
+if ( ! $framework_active ) {
+	WP_CLI::log( '42-framework not detected — skipped permalinks, front page and menus.' );
+	WP_CLI::success( sprintf( 'Demo content ready (%d posts).', $created ) );
+	return;
+}
+
+/* Permalinks: /%category%/%postname%/. Soft flush so we never rewrite the
+ * mounted .htaccess. Idempotent — re-setting the same structure is a no-op. */
+if ( '/%category%/%postname%/' !== get_option( 'permalink_structure' ) ) {
+	global $wp_rewrite;
+	$wp_rewrite->set_permalink_structure( '/%category%/%postname%/' );
+	$wp_rewrite->flush_rules( false );
+	WP_CLI::log( 'Permalinks set to /%category%/%postname%/.' );
+}
+
+/* Front page: a `42wp_homepage` post (falls back to a page if the type isn't
+ * registered), reused when it already exists. */
+$home_type = post_type_exists( '42wp_homepage' ) ? '42wp_homepage' : 'page';
+$home_ids  = get_posts( [ 'post_type' => $home_type, 'name' => 'homepage', 'post_status' => 'any', 'numberposts' => 1, 'fields' => 'ids' ] );
+$home_id   = $home_ids ? (int) $home_ids[0] : 0;
+if ( ! $home_id ) {
+	$home_id = wp_insert_post( [
+		'post_title'  => 'Homepage',
+		'post_name'   => 'homepage',
+		'post_status' => 'publish',
+		'post_type'   => $home_type,
+		'post_author' => 1,
+	], true );
+}
+if ( ! is_wp_error( $home_id ) && $home_id ) {
+	update_post_meta( $home_id, '42wp_seo_metadata_noindex', '1' );
+	update_option( 'show_on_front', 'page' );
+	update_option( 'page_on_front', (int) $home_id );
+	WP_CLI::log( sprintf( 'Front page set to %s #%d.', $home_type, $home_id ) );
+}
+
+/* Menus: 4 category-driven menus, populated once and assigned to the theme's
+ * registered locations. The category items reuse the terms created above. */
+$cat_by_name = [];
+foreach ( $cat_names as $cn ) {
+	$term = get_term_by( 'name', $cn, 'category' );
+	if ( $term ) {
+		$cat_by_name[ $cn ] = (int) $term->term_id;
+	}
+}
+
+$menu_specs = [
+	'42wp_menu_header_primary'   => [
+		'name'  => 'Header Primário',
+		'items' => [ [ 'cat', 'Política' ], [ 'cat', 'Mundo' ], [ 'cat', 'Cultura' ], [ 'cat', 'Entretenimento' ] ],
+	],
+	'42wp_menu_header_secondary' => [
+		'name'  => 'Header Secundário',
+		'items' => [ [ 'cat', 'Saúde' ], [ 'cat', 'Brasil' ], [ 'cat', 'Tecnologia' ] ],
+	],
+	'42wp_menu_footer_primary'   => [
+		'name'  => 'Footer Primário',
+		'items' => [
+			[ 'cat', 'Esportes', [ [ 'cat', 'Entretenimento' ], [ 'cat', 'Brasil' ], [ 'cat', 'Tecnologia' ] ] ],
+			[ 'cat', 'Economia', [ [ 'cat', 'Política' ], [ 'cat', 'Saúde' ], [ 'cat', 'Esportes' ] ] ],
+			[ 'cat', 'Ciência', [ [ 'cat', 'Mundo' ], [ 'cat', 'Cultura' ] ] ],
+			[ 'cat', 'Tecnologia', [ [ 'cat', 'Saúde' ], [ 'cat', 'Brasil' ], [ 'cat', 'Economia' ] ] ],
+			[ 'cat', 'Política', [ [ 'cat', 'Mundo' ], [ 'cat', 'Cultura' ], [ 'cat', 'Entretenimento' ], [ 'cat', 'Ciência' ] ] ],
+		],
+	],
+	'42wp_menu_footer_social'    => [
+		'name'  => 'Footer Social',
+		'items' => [ [ 'link', 'YouTube', 'https://youtube.com' ], [ 'link', 'X', 'https://x.com' ], [ 'link', 'Instagram', 'https://instagram.com' ] ],
+	],
+];
+
+// Recursively add menu items (category archives or custom links), honoring nesting.
+$add_items = static function ( $menu_id, array $items, $parent = 0 ) use ( &$add_items, $cat_by_name ) {
+	foreach ( $items as $item ) {
+		if ( 'cat' === $item[0] ) {
+			if ( empty( $cat_by_name[ $item[1] ] ) ) {
+				continue;
+			}
+			$new_item = wp_update_nav_menu_item( $menu_id, 0, [
+				'menu-item-title'     => $item[1],
+				'menu-item-type'      => 'taxonomy',
+				'menu-item-object'    => 'category',
+				'menu-item-object-id' => $cat_by_name[ $item[1] ],
+				'menu-item-parent-id' => $parent,
+				'menu-item-status'    => 'publish',
+			] );
+			if ( ! is_wp_error( $new_item ) && ! empty( $item[2] ) ) {
+				$add_items( $menu_id, $item[2], (int) $new_item );
+			}
+		} elseif ( 'link' === $item[0] ) {
+			wp_update_nav_menu_item( $menu_id, 0, [
+				'menu-item-title'     => $item[1],
+				'menu-item-url'       => $item[2],
+				'menu-item-type'      => 'custom',
+				'menu-item-parent-id' => $parent,
+				'menu-item-status'    => 'publish',
+			] );
+		}
+	}
+};
+
+$registered = get_registered_nav_menus();
+$locations  = get_theme_mod( 'nav_menu_locations', [] );
+if ( ! is_array( $locations ) ) {
+	$locations = [];
+}
+
+$menus_done = 0;
+foreach ( $menu_specs as $location => $spec ) {
+	$menu = wp_get_nav_menu_object( $spec['name'] );
+	if ( $menu ) {
+		$menu_id = (int) $menu->term_id;
+	} else {
+		$menu_id = wp_create_nav_menu( $spec['name'] );
+		if ( is_wp_error( $menu_id ) ) {
+			continue;
+		}
+	}
+
+	// Populate only when empty, so re-runs don't duplicate items.
+	if ( empty( wp_get_nav_menu_items( $menu_id ) ) ) {
+		$add_items( $menu_id, $spec['items'] );
+	}
+
+	if ( isset( $registered[ $location ] ) ) {
+		$locations[ $location ] = (int) $menu_id;
+	}
+	$menus_done++;
+}
+set_theme_mod( 'nav_menu_locations', $locations );
+WP_CLI::log( sprintf( 'Menus ready: %d created/assigned.', $menus_done ) );
+
+WP_CLI::success( sprintf( 'Demo content ready: %d posts, front page and %d menus.', $created, $menus_done ) );

package/src/templates/project.Dockerfile

@@ -11,6 +11,16 @@ RUN echo "xdebug.mode=debug" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.
     && echo "xdebug.client_host=host.docker.internal" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini \
     && echo "xdebug.start_with_request=yes" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
 
+# Raise the upload limit to 2G (WP caps at min(upload_max_filesize, post_max_size);
+# the PHP default post_max_size is only 8M, so both must be raised together).
+RUN { \
+        echo "upload_max_filesize = 2048M"; \
+        echo "post_max_size = 2048M"; \
+        echo "memory_limit = 2048M"; \
+        echo "max_execution_time = 300"; \
+        echo "max_input_time = 300"; \
+    } > /usr/local/etc/php/conf.d/uploads.ini
+
 RUN curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar \
     && chmod +x wp-cli.phar \
     && mv wp-cli.phar /usr/local/bin/wp