@42wp/dev-env 1.0.0

package/src/lib/paths.js

@@ -0,0 +1,34 @@
+// Filesystem layout. Everything the tool persists at runtime lives under the
+// data dir, which defaults to ~/.42wp and can be
+// overridden with FORTYTWO_HOME. Bundled templates live inside the package and
+// are resolved relative to this module via import.meta.url.
+
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url)); // .../src/lib
+
+export function dataDir() {
+  return process.env.FORTYTWO_HOME || path.join(os.homedir(), '.42wp');
+}
+
+export function projectsDir() {
+  return path.join(dataDir(), 'projects');
+}
+
+export function projectDir(name) {
+  return path.join(projectsDir(), name);
+}
+
+export function globalComposePath() {
+  return path.join(dataDir(), 'docker-compose.global.yml');
+}
+
+export function templatesDir() {
+  return path.join(here, '..', 'templates');
+}
+
+export function templatePath(name) {
+  return path.join(templatesDir(), name);
+}

package/src/lib/prompt.js

@@ -0,0 +1,17 @@
+// Minimal interactive yes/no prompt for destructive actions.
+
+import { createInterface } from 'node:readline/promises';
+
+// Ask a y/N question on the terminal. Defaults to "no" (safe for destructive ops).
+// Callers should only invoke this when process.stdin.isTTY is true.
+export async function confirm(question, { defaultYes = false } = {}) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const suffix = defaultYes ? '[Y/n]' : '[y/N]';
+    const answer = (await rl.question(`${question} ${suffix} `)).trim().toLowerCase();
+    if (!answer) return defaultYes;
+    return answer === 'y' || answer === 'yes';
+  } finally {
+    rl.close();
+  }
+}

package/src/lib/render.js

@@ -0,0 +1,41 @@
+// Template rendering for the files `start` generates, plus a helper to make sure
+// the global compose file exists in the data dir before the global layer comes up.
+
+import fs from 'node:fs/promises';
+import { dataDir, globalComposePath, templatePath } from './paths.js';
+
+// Replace {{VAR}} placeholders. Throws if a placeholder has no matching var, so a
+// typo fails loudly instead of writing a half-rendered file.
+export function render(template, vars) {
+  return template.replace(/\{\{(\w+)\}\}/g, (match, key) => {
+    if (!Object.prototype.hasOwnProperty.call(vars, key)) {
+      throw new Error(`Missing template variable: ${key}`);
+    }
+    return vars[key];
+  });
+}
+
+export async function readTemplate(name) {
+  return fs.readFile(templatePath(name), 'utf8');
+}
+
+export async function renderTemplate(name, vars) {
+  return render(await readTemplate(name), vars);
+}
+
+// Write the bundled global compose into the data dir if it isn't there yet.
+// Never overwrites an existing file, so a user's edits (and their mysql-data
+// binding) are preserved.
+export async function ensureGlobalCompose() {
+  const dest = globalComposePath();
+  try {
+    await fs.access(dest);
+    return dest; // already present
+  } catch {
+    // The data dir may not exist yet on a first run — create it before writing.
+    await fs.mkdir(dataDir(), { recursive: true });
+    const contents = await readTemplate('docker-compose.global.yml');
+    await fs.writeFile(dest, contents, 'utf8');
+    return dest;
+  }
+}

package/src/lib/salts.js

@@ -0,0 +1,57 @@
+// WordPress secret keys/salts. Mirrors the original `curl api.wordpress.org/.../salt/`,
+// but with a local fallback so `start` still works offline (the original would have
+// written an empty salts block in that case).
+
+import crypto from 'node:crypto';
+
+const SALT_URL = 'https://api.wordpress.org/secret-key/1.1/salt/';
+
+const KEYS = [
+  'AUTH_KEY',
+  'SECURE_AUTH_KEY',
+  'LOGGED_IN_KEY',
+  'NONCE_KEY',
+  'AUTH_SALT',
+  'SECURE_AUTH_SALT',
+  'LOGGED_IN_SALT',
+  'NONCE_SALT',
+];
+
+// Printable ASCII excluding ' and \ so the value is safe inside a single-quoted PHP string.
+const CHARSET = (() => {
+  let s = '';
+  for (let c = 33; c <= 126; c++) {
+    if (c === 39 /* ' */ || c === 92 /* \ */) continue;
+    s += String.fromCharCode(c);
+  }
+  return s;
+})();
+
+function randomSalt(length = 64) {
+  const bytes = crypto.randomBytes(length);
+  let out = '';
+  for (let i = 0; i < length; i++) out += CHARSET[bytes[i] % CHARSET.length];
+  return out;
+}
+
+export function generateSaltsLocally() {
+  return KEYS.map((key) => `define( '${key}', '${randomSalt()}' );`).join('\n');
+}
+
+// Returns { salts, fromFallback }. Tries api.wordpress.org first (5s timeout),
+// then falls back to locally generated salts.
+export async function fetchSalts() {
+  try {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 5000);
+    const res = await fetch(SALT_URL, { signal: controller.signal });
+    clearTimeout(timer);
+    if (res.ok) {
+      const text = (await res.text()).trim();
+      if (text.includes('define(')) return { salts: text, fromFallback: false };
+    }
+  } catch {
+    // network error / abort -> fall through to local generation
+  }
+  return { salts: generateSaltsLocally(), fromFallback: true };
+}

package/src/lib/seeder.js

@@ -0,0 +1,14 @@
+// Run the demo-content seeder (demo-seed.php) against a running container by
+// piping it to `wp eval-file -`. Shared by `start --demo-content` and `seed`.
+
+import { runWithInput } from './docker.js';
+import { readTemplate } from './render.js';
+
+export async function runSeeder(container, count) {
+  const seeder = await readTemplate('demo-seed.php');
+  await runWithInput(
+    'docker',
+    ['exec', '-i', container, 'wp', 'eval-file', '-', String(count), '--allow-root'],
+    seeder,
+  );
+}

package/src/lib/wait.js

@@ -0,0 +1,26 @@
+// Readiness polling — replaces the original's fixed `sleep 10` / `sleep 5`.
+// Repeatedly runs an async check until it returns truthy or the timeout elapses.
+
+import { t } from './i18n.js';
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+// check: async () => boolean. Resolves when check() is truthy; rejects on timeout.
+export async function pollUntil(check, { timeout = 60000, interval = 1500, label = '' } = {}) {
+  const deadline = Date.now() + timeout;
+  // First attempt immediately, then poll on the interval.
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    let ok = false;
+    try {
+      ok = await check();
+    } catch {
+      ok = false;
+    }
+    if (ok) return;
+    if (Date.now() >= deadline) {
+      throw new Error(t('wait.timeout', { label, seconds: Math.round(timeout / 1000) }));
+    }
+    await sleep(interval);
+  }
+}

package/src/locales/en.js

@@ -0,0 +1,91 @@
+// English message catalog. Keys are referenced via t('key', params) in src/lib/i18n.js.
+// Placeholders use ${name} and are filled from the params object.
+
+export default {
+  // generic
+  'err.prefix': 'Error',
+  'docker.notRunning': 'Docker is not running.',
+
+  // global layer
+  'global.starting': 'Starting the Global Layer...',
+  'global.stopping': 'Stopping the Global Layer...',
+  'global.waitingMysql': 'Waiting for MySQL to be ready...',
+  'global.invalid': "Invalid global command. Use 'start' or 'stop'.",
+
+  // start
+  'start.needName': 'You must provide a project name. e.g.: 42wp start jovempan',
+  'start.preparing': 'Preparing environment for ${domain}...',
+  'start.creatingDb': 'Creating database: ${db}',
+  'start.genConfig': 'Generating ephemeral wp-config.php...',
+  'start.saltsFallback': 'Could not reach api.wordpress.org; generated salts locally.',
+  'start.genDockerfile': 'Generating Dockerfile (${image})...',
+  'start.genCompose': 'Generating project docker-compose...',
+  'start.vipCloning': 'Cloning WordPress VIP mu-plugins (${repo})...',
+  'start.vipUpdating': 'Updating WordPress VIP mu-plugins...',
+  'start.upping': 'Starting project containers...',
+  'start.waitingWp': 'Waiting for the WordPress container to respond...',
+  'start.installing': 'Running silent WordPress install...',
+  'start.enablingMultisite': 'Enabling multisite (network tables + wp-config constants)...',
+  'start.permalinks': 'Configuring permalinks...',
+  'start.demoGenerating': 'Seeding ${count} demo posts (authors, tags, categories, images)...',
+  'start.demoFailed': 'Could not generate demo content (continuing anyway).',
+  'start.success': 'Success! The project is online.',
+  'start.url': 'URL:      ${url}',
+  'start.admin': 'Admin:    ${url}/wp-admin',
+  'start.user': 'User:     ${user}',
+  'start.pass': 'Password: ${pass}',
+  'start.multisite': 'Multisite: ${mode}. Network admin: ${url}/wp-admin/network/',
+
+  // update
+  'update.needName': 'Tell me which project to update. e.g.: 42wp update jovempan',
+  '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.notFound': "Project '${name}' not found at ${dir}.",
+  'rm.confirm':
+    "Remove '${name}'? This deletes its container, image and database. Your repository is kept.",
+  'rm.needYes': 'Refusing to remove without confirmation. Re-run with --yes.',
+  'rm.cancelled': 'Cancelled. Nothing was removed.',
+  'rm.removingContainers': 'Removing containers and image for ${name}...',
+  'rm.droppingDb': 'Dropping database: ${db}',
+  'rm.mysqlDown': 'Global MySQL is not running — skipped dropping database ${db}.',
+  'rm.removingData': 'Removing project data: ${dir}',
+  'rm.done': "Removed '${name}'. Your repository was left untouched.",
+
+  // seed
+  'seed.needName': 'Tell me which project to seed. e.g.: 42wp seed jovempan',
+  '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.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.notRunning': 'Container ${container} is not running.',
+
+  // validation
+  'name.invalid':
+    "Invalid project name '${name}'. Use only letters, numbers, hyphens and underscores.",
+
+  // usage
+  'usage.line': 'Usage: 42wp <command> [project] [arguments]',
+  'usage.commands': 'Commands:',
+  '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.',
+  'usage.rm': '  rm <project>       Remove a site (container, image, database) — keeps your repo.',
+  'usage.seed': '  seed <project> [n]  Generate demo content in a running project (default 200 posts).',
+  'usage.wp': '  wp <project> ...   Run a WP-CLI command inside the container.',
+  'usage.globalStart': '  global start       Start the Traefik proxy and MySQL.',
+  'usage.globalStop': '  global stop        Stop the global infrastructure.',
+
+  // wait
+  'wait.timeout': 'Timed out waiting for ${label} after ${seconds}s.',
+};

package/src/locales/pt.js

@@ -0,0 +1,91 @@
+// Catálogo de mensagens em Português. As chaves são as mesmas de en.js.
+// Mantém os textos originais do 42script.sh.
+
+export default {
+  // genérico
+  'err.prefix': 'Erro',
+  'docker.notRunning': 'Docker não está rodando.',
+
+  // camada global
+  'global.starting': 'Iniciando a Camada Global...',
+  'global.stopping': 'Parando Camada Global...',
+  'global.waitingMysql': 'Aguardando MySQL iniciar...',
+  '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.preparing': 'Preparando ambiente para ${domain}...',
+  'start.creatingDb': 'Criando banco de dados: ${db}',
+  'start.genConfig': 'Gerando wp-config.php efêmero...',
+  'start.saltsFallback': 'Não foi possível acessar api.wordpress.org; salts gerados localmente.',
+  'start.genDockerfile': 'Gerando Dockerfile (${image})...',
+  'start.genCompose': 'Gerando docker-compose do projeto...',
+  'start.vipCloning': 'Clonando os mu-plugins do WordPress VIP (${repo})...',
+  'start.vipUpdating': 'Atualizando os mu-plugins do WordPress VIP...',
+  'start.upping': 'Subindo containers do projeto...',
+  'start.waitingWp': 'Aguardando o container WP responder...',
+  'start.installing': 'Executando instalação silenciosa do WordPress...',
+  '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)...',
+  'start.demoFailed': 'Não foi possível gerar o conteúdo de demonstração (continuando mesmo assim).',
+  'start.success': 'Sucesso! O projeto está online.',
+  'start.url': 'URL:      ${url}',
+  'start.admin': 'Admin:    ${url}/wp-admin',
+  'start.user': 'Usuário:  ${user}',
+  'start.pass': 'Senha:    ${pass}',
+  'start.multisite': 'Multisite: ${mode}. Admin da rede: ${url}/wp-admin/network/',
+
+  // update
+  'update.needName': 'Informe o projeto para atualizar. Ex: 42wp update jovempan',
+  '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.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.",
+  'rm.needYes': 'Removendo apenas com confirmação. Rode novamente com --yes.',
+  'rm.cancelled': 'Cancelado. Nada foi removido.',
+  'rm.removingContainers': 'Removendo containers e imagem de ${name}...',
+  'rm.droppingDb': 'Removendo banco de dados: ${db}',
+  'rm.mysqlDown': 'O MySQL global não está rodando — banco ${db} não foi removido.',
+  'rm.removingData': 'Removendo dados do projeto: ${dir}',
+  'rm.done': "Removido '${name}'. Seu repositório não foi tocado.",
+
+  // seed
+  'seed.needName': 'Informe o projeto para popular. Ex: 42wp seed jovempan',
+  '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.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.notRunning': 'Container ${container} não está rodando.',
+
+  // validação
+  'name.invalid':
+    "Nome de projeto inválido '${name}'. Use apenas letras, números, hífens e underscores.",
+
+  // uso
+  'usage.line': 'Uso: 42wp <comando> [projeto] [argumentos]',
+  'usage.commands': 'Comandos:',
+  '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.',
+  'usage.rm': '  rm <projeto>       Remove um site (container, imagem, banco) — mantém seu repositório.',
+  'usage.seed': '  seed <projeto> [n]  Gera conteúdo de demo em um projeto rodando (padrão 200 posts).',
+  'usage.wp': '  wp <projeto> ...   Executa um comando WP-CLI no container.',
+  'usage.globalStart': '  global start       Inicia o proxy Traefik e o MySQL.',
+  'usage.globalStop': '  global stop        Para a infraestrutura global.',
+
+  // wait
+  'wait.timeout': 'Tempo esgotado aguardando ${label} após ${seconds}s.',
+};

package/src/templates/demo-seed.php

@@ -0,0 +1,202 @@
+<?php
+/**
+ * 42WP demo content seeder — run by @42wp/dev-env's `--demo-content` flag via:
+ *   wp eval-file - <count>     (script piped on STDIN, post count as the argument)
+ *
+ * Creates:
+ *   - ~10 `42wp_author` terms (Portuguese names), ~10 tags, ~10 categories
+ *   - a pool of free images downloaded once from picsum.photos and reused
+ *   - <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.
+ *
+ * This file is managed by the dev environment; edits will be overwritten.
+ */
+
+if ( ! defined( 'WP_CLI' ) || ! WP_CLI ) {
+	return;
+}
+
+// media_handle_sideload() lives in wp-admin/includes/media.php.
+if ( ! function_exists( 'media_handle_sideload' ) ) {
+	require_once ABSPATH . 'wp-admin/includes/file.php';
+	require_once ABSPATH . 'wp-admin/includes/image.php';
+	require_once ABSPATH . 'wp-admin/includes/media.php';
+}
+
+$count = isset( $args[0] ) ? max( 1, (int) $args[0] ) : 200;
+
+/* -------------------------------------------------------------------------- *
+ * Taxonomy terms
+ * -------------------------------------------------------------------------- */
+
+// The `42wp_author` taxonomy is registered by the project itself (the 42-framework
+// composer mu-plugin), so we don't register it here. If it isn't available, the
+// author terms below are simply skipped (wp_insert_term returns a WP_Error).
+
+$author_names = [ 'José Almeida', 'Ricardo Feitosa', 'Júlia Silva', 'Marina Costa', 'Pedro Henrique', 'Ana Beatriz', 'Carlos Eduardo', 'Fernanda Lima', 'Rafael Oliveira', 'Beatriz Santos' ];
+$tag_names    = [ 'Guerra', 'Viagem', 'Reality Show', 'Tecnologia', 'Economia', 'Cultura', 'Saúde', 'Educação', 'Meio Ambiente', 'Entretenimento' ];
+$cat_names    = [ 'Brasil', 'Mundo', 'Esportes', 'Política', 'Ciência', 'Cultura', 'Tecnologia', 'Entretenimento', 'Saúde', 'Economia' ];
+
+$ensure_terms = static function ( array $names, $taxonomy ) {
+	$ids = [];
+	foreach ( $names as $name ) {
+		$existing = term_exists( $name, $taxonomy );
+		if ( $existing ) {
+			$ids[] = (int) ( is_array( $existing ) ? $existing['term_id'] : $existing );
+			continue;
+		}
+		$new = wp_insert_term( $name, $taxonomy );
+		if ( ! is_wp_error( $new ) ) {
+			$ids[] = (int) $new['term_id'];
+		}
+	}
+	return $ids;
+};
+
+$author_ids = $ensure_terms( $author_names, '42wp_author' );
+$tag_ids    = $ensure_terms( $tag_names, 'post_tag' );
+$cat_ids    = $ensure_terms( $cat_names, 'category' );
+
+WP_CLI::log( sprintf( 'Terms ready: %d authors, %d tags, %d categories.', count( $author_ids ), count( $tag_ids ), count( $cat_ids ) ) );
+
+/* -------------------------------------------------------------------------- *
+ * Image pool — downloaded once from picsum.photos, reused across posts
+ * -------------------------------------------------------------------------- */
+
+$pool_size = min( $count, 25 );
+$image_ids = [];
+for ( $i = 0; $i < $pool_size; $i++ ) {
+	$seed = 'fortytwo-' . wp_generate_password( 10, false );
+	$url  = "https://picsum.photos/seed/{$seed}/1200/630.jpg";
+	$id   = media_sideload_image( $url, 0, null, 'id' );
+	if ( ! is_wp_error( $id ) ) {
+		$image_ids[] = (int) $id;
+	}
+}
+WP_CLI::log( sprintf( 'Images: %d/%d downloaded from picsum.photos.', count( $image_ids ), $pool_size ) );
+
+/* -------------------------------------------------------------------------- *
+ * Lorem ipsum corpus + helpers
+ * -------------------------------------------------------------------------- */
+
+$sentences = [
+	'Lorem ipsum dolor sit amet, consectetur adipiscing elit',
+	'Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua',
+	'Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris',
+	'Duis aute irure dolor in reprehenderit in voluptate velit esse cillum',
+	'Excepteur sint occaecat cupidatat non proident sunt in culpa',
+	'Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit',
+	'Neque porro quisquam est qui dolorem ipsum quia dolor sit amet',
+	'Quis autem vel eum iure reprehenderit qui in ea voluptate velit',
+	'At vero eos et accusamus et iusto odio dignissimos ducimus',
+	'Et harum quidem rerum facilis est et expedita distinctio',
+	'Temporibus autem quibusdam et aut officiis debitis aut rerum',
+	'Itaque earum rerum hic tenetur a sapiente delectus ut aut',
+	'Vestibulum ante ipsum primis in faucibus orci luctus et ultrices',
+	'Pellentesque habitant morbi tristique senectus et netus malesuada',
+	'Curabitur pretium tincidunt lacus gravida ornare quam viverra',
+	'Donec sollicitudin molestie malesuada nulla quis lorem ut libero',
+	'Vivamus suscipit tortor eget felis porttitor volutpat aliquam',
+	'Cras ultricies ligula sed magna dictum porta morbi leo risus',
+];
+
+$para = static function ( $min = 3, $max = 6 ) use ( $sentences ) {
+	$n      = wp_rand( $min, $max );
+	$picked = [];
+	for ( $i = 0; $i < $n; $i++ ) {
+		$picked[] = $sentences[ array_rand( $sentences ) ];
+	}
+	return implode( '. ', $picked ) . '.';
+};
+
+$heading = static function ( $words = 3 ) use ( $sentences ) {
+	$parts = explode( ' ', $sentences[ array_rand( $sentences ) ] );
+	$parts = array_slice( $parts, 0, $words );
+	return ucfirst( strtolower( implode( ' ', $parts ) ) );
+};
+
+// Pick between $min and $max random values from $arr (without repeats).
+$pick = static function ( array $arr, $min, $max ) {
+	if ( empty( $arr ) ) {
+		return [];
+	}
+	$n    = min( count( $arr ), wp_rand( $min, $max ) );
+	$keys = (array) array_rand( $arr, $n );
+	return array_map( static function ( $k ) use ( $arr ) {
+		return $arr[ $k ];
+	}, $keys );
+};
+
+$figure = static function () use ( $image_ids ) {
+	if ( empty( $image_ids ) ) {
+		return '';
+	}
+	$src = wp_get_attachment_image_url( $image_ids[ array_rand( $image_ids ) ], 'large' );
+	if ( ! $src ) {
+		return '';
+	}
+	return '<figure><img src="' . esc_url( $src ) . '" alt="" loading="lazy" /></figure>' . "\n";
+};
+
+/* -------------------------------------------------------------------------- *
+ * Posts
+ * -------------------------------------------------------------------------- */
+
+$now      = time();
+$two_year = 2 * YEAR_IN_SECONDS;
+$created  = 0;
+
+for ( $i = 0; $i < $count; $i++ ) {
+	$title = rtrim( $sentences[ array_rand( $sentences ) ], '.' );
+
+	$content  = '<h1>' . esc_html( ucfirst( $heading( 5 ) ) ) . "</h1>\n";
+	$content .= '<p>' . $para( 3, 5 ) . "</p>\n";
+	$content .= $figure();
+	$content .= '<h2>' . esc_html( $heading( 3 ) ) . "</h2>\n";
+	$content .= '<p><strong>' . $heading( 2 ) . '.</strong> ' . $para( 2, 4 ) . ' <em>' . $heading( 3 ) . '.</em></p>' . "\n";
+	$content .= "<ul>\n\t<li>" . $heading( 4 ) . "</li>\n\t<li>" . $heading( 4 ) . "</li>\n\t<li>" . $heading( 4 ) . "</li>\n</ul>\n";
+	$content .= '<blockquote><p>' . $sentences[ array_rand( $sentences ) ] . ".</p></blockquote>\n";
+	$content .= '<h2>' . esc_html( $heading( 3 ) ) . "</h2>\n";
+	$content .= '<p>' . $para( 3, 5 ) . "</p>\n";
+	$content .= $figure();
+	$content .= '<h3>' . esc_html( $heading( 2 ) ) . "</h3>\n";
+	$content .= '<p>' . $para( 2, 4 ) . " <a href=\"#\">" . $heading( 2 ) . "</a>.</p>\n";
+
+	$excerpt = $para( 1, 2 ); // plain text, no HTML
+
+	$date_ts  = $now - wp_rand( 0, $two_year ); // always in the past
+	$post_id  = wp_insert_post( [
+		'post_title'    => ucfirst( $title ),
+		'post_content'  => $content,
+		'post_excerpt'  => $excerpt,
+		'post_status'   => 'publish',
+		'post_type'     => 'post',
+		'post_author'   => 1,
+		'post_date'     => date( 'Y-m-d H:i:s', $date_ts ),
+		'post_date_gmt' => gmdate( 'Y-m-d H:i:s', $date_ts ),
+	], true );
+
+	if ( is_wp_error( $post_id ) ) {
+		continue;
+	}
+
+	if ( $cat_ids ) {
+		wp_set_object_terms( $post_id, $cat_ids[ array_rand( $cat_ids ) ], 'category' );
+	}
+	if ( $tag_ids ) {
+		wp_set_object_terms( $post_id, $pick( $tag_ids, 2, 5 ), 'post_tag' );
+	}
+	if ( $author_ids ) {
+		wp_set_object_terms( $post_id, $pick( $author_ids, 1, 3 ), '42wp_author' );
+	}
+	if ( $image_ids ) {
+		set_post_thumbnail( $post_id, $image_ids[ array_rand( $image_ids ) ] );
+	}
+
+	$created++;
+	if ( 0 === $created % 25 ) {
+		WP_CLI::log( sprintf( '  %d/%d posts created...', $created, $count ) );
+	}
+}
+
+WP_CLI::success( sprintf( 'Created %d demo posts.', $created ) );

package/src/templates/dev-helper.php

@@ -0,0 +1,45 @@
+<?php
+/**
+ * Plugin Name: 42WP Dev Helper
+ * Description: Local dev shims injected by @42wp/dev-env (--vip). Ensures the
+ *              WordPress admin media/file functions (media_handle_sideload,
+ *              download_url, media_sideload_image, ...) are loaded in admin, REST
+ *              and CLI contexts. Works around plugins such as FakerPress that call
+ *              these without loading wp-admin/includes/media.php themselves — a
+ *              common failure on VIP, where other code loads file.php early.
+ * Author: 42WP
+ *
+ * This file is managed by the dev environment and mounted read-only into the
+ * container; do not edit by hand.
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+if ( ! function_exists( 'fortytwo_wp_load_media_includes' ) ) {
+	/**
+	 * Load the wp-admin media includes if they aren't already present.
+	 *
+	 * media_handle_sideload() lives in wp-admin/includes/media.php, while
+	 * download_url() lives in file.php — plugins that guard on the latter can
+	 * skip loading the former and fatal. Loading all three here is safe and idempotent.
+	 */
+	function fortytwo_wp_load_media_includes() {
+		if ( function_exists( 'media_handle_sideload' ) ) {
+			return;
+		}
+		require_once ABSPATH . 'wp-admin/includes/file.php';
+		require_once ABSPATH . 'wp-admin/includes/image.php';
+		require_once ABSPATH . 'wp-admin/includes/media.php';
+	}
+}
+
+// Cover the contexts where attachment generation runs: classic admin, the REST
+// API (FakerPress 0.9+ generates via REST), and WP-CLI.
+add_action( 'admin_init', 'fortytwo_wp_load_media_includes' );
+add_action( 'rest_api_init', 'fortytwo_wp_load_media_includes' );
+
+if ( defined( 'WP_CLI' ) && WP_CLI ) {
+	fortytwo_wp_load_media_includes();
+}