@wp-operations/wp-app 0.3.0 → 0.4.0

package/README.md

@@ -1,8 +1,6 @@
 # @wp-operations/wp-app
 
-**The `wp-now` revival.** A zero-config local WordPress dev server on `@php-wasm/node`: no Docker, no MySQL, no XAMPP. Point it at a theme, a plugin, or a full core checkout and it starts.
-
-When `wp-now` was deprecated in favor of the blueprint-centric Playground CLI, the simple `wp-now start` workflow went with it. `wp-app` brings it back — same one-command experience, running on the **current** php-wasm engine (PHP 7.4 – 8.5).
+A zero-config local WordPress dev server on `@php-wasm/node`: no Docker, no MySQL, no XAMPP. Point it at a theme, a plugin, a full core checkout, or a wp-app project, and it starts.
 
 ## Install
 
@@ -15,48 +13,37 @@ Requires Node.js >= 20.10.
 ## Usage
 
 ```bash
-wp-app start                       # auto-detects project type from cwd
-wp-app start --path=my-theme       # explicit path
-wp-app start --php=8.3 --wp=6.8    # pin PHP / WordPress versions
-wp-app start --wp=classicpress     # run ClassicPress instead (lightweight, no Gutenberg)
-wp-app start --port=8881 --reset   # fresh site (wipes the managed WordPress + database)
-wp-app dev                         # start + restart on file changes
-wp-app build                       # composer install + npm build script, when present
-wp-app php -- -r 'echo PHP_VERSION;'   # PHP CLI via php-wasm
-wp-app php -- script.php               # run a PHP file
+wp-app start
+wp-app start --path=my-app
+wp-app start --php=8.3 --wp=6.8
+wp-app start --wp=classicpress
+wp-app start --port=8881 --reset
+wp-app dev
+wp-app build
+wp-app install
+wp-app update
+wp-app create my-app
+wp-app php -- -r 'echo PHP_VERSION;'
+wp-app php -- script.php
 ```
 
 Login: `admin` / `password`.
 
-## How data is stored
-
-- Core downloads are cached once in `~/.wp-app/cache/`
-- Each project gets a full persistent WordPress site in `~/.wp-app/sites/<project>-<hash>/` — files and SQLite database survive restarts; `--reset` deletes exactly this directory and never your project
-- Your project directory is mounted *into* that site (as a theme, plugin, or wp-content overlay) — edits are live without restarts
-- Set the `WP_APP_HOME` environment variable to relocate all of the above (CI, portable drives, or the `.local` repo convention via `@wp-operations/wp-ide`)
-
 ## Modes
 
-Auto-detected from the project directory, or forced with `--mode`:
+Auto-detected from the project directory, or forced with `--mode`. Checked in this order — first match wins:
 
 | Mode | Detected when | What runs |
 |------|--------------|-----------|
-| `theme` | `style.css` with a Theme Name header | Managed WP + your directory mounted as a theme, auto-activated |
-| `plugin` | PHP file with a Plugin Name header | Managed WP + your directory mounted as a plugin, auto-activated |
+| `wp-app` | `composer.json` with `"type": "wp-app"` | `wp-app` |
+| `wordpress` | Full WordPress core checkout | Your core served directly, SQLite-backed |
+| `classicpress` | Full ClassicPress core checkout | Your core served directly, SQLite-backed |
 | `wp-content` | `plugins/` + `themes/` dirs | Managed WP + your entries overlaid on `wp-content` |
-| `wordpress` | Full core checkout | Your core served directly, SQLite-backed |
-| `wordpress-develop` | Core dev checkout | The `build/` directory |
+| `plugin` | PHP file with a Plugin Name header | Managed WP + your directory mounted as a plugin, auto-activated |
+| `theme` | `style.css` with a Theme Name header | Managed WP + your directory mounted as a theme, auto-activated |
 | `index` | An `index.php` | Plain PHP server, no WordPress |
-| `playground` | None of the above (e.g. empty dir) | Fresh managed install |
-
-## ClassicPress
-
-`--wp=classicpress` fetches the latest ClassicPress release; `--wp=classicpress-2.4.1` pins a version. Everything else (modes, SQLite, mounts) works identically.
-
-## Part of wp-operations
 
-`wp-app` is the foundation of [wp-operations](https://github.com/wordpress-operations/wordpress-operations) — an open-source operations toolchain for classic WordPress development: PSR-4 vendor packages as plugins, an AI skills library with security guidelines, monorepo tooling (`@wp-operations/wp-ide`), and a unified operations CLI (`@wp-operations/wp-ops`).
 
-## Credits & License
+## License
 
 GPL-2.0-or-later. Continues the workflow of [`@wp-now/wp-now`](https://github.com/WordPress/playground-tools) by the WordPress contributors, rebuilt on `@php-wasm/*`.

package/dist/index.js

@@ -10,8 +10,8 @@ function getCodeSpaceURL(port) {
 }
 
 // src/engine.ts
-import fs10 from "fs";
-import path9 from "path";
+import fs11 from "fs";
+import path10 from "path";
 import { createNodeFsMountHandler } from "@php-wasm/node";
 
 // src/boot.ts
@@ -37,7 +37,18 @@ async function createPhp(phpVersion) {
   return php;
 }
 function createRequestHandler(php, documentRoot, absoluteUrl) {
-  return new PHPRequestHandler({ php, documentRoot, absoluteUrl });
+  return new PHPRequestHandler({
+    php,
+    documentRoot,
+    absoluteUrl,
+    // Route unmatched URLs (permalinks, admin-ajax) to index.php, not 404.
+    getFileNotFoundAction: () => ({
+      type: "internal-redirect",
+      uri: "/index.php"
+    }),
+    // Let Set-Cookie pass through to the real HTTP server (express).
+    cookieStore: false
+  });
 }
 async function runPhp(php, code) {
   const response = await php.run({ code: `<?php ${code}` });
@@ -140,18 +151,22 @@ function defineSiteConstants(php, siteUrl, databaseDir) {
   php.defineConstant("DB_DIR", databaseDir);
   php.defineConstant("DB_FILE", ".ht.sqlite");
   php.defineConstant("WP_SQLITE_AST_DRIVER", true);
+  php.defineConstant("DISABLE_WP_CRON", true);
 }
 async function runInstaller(requestHandler) {
+  const adminUser = process.env.WP_ADMIN_USER || "admin";
+  const adminPassword = process.env.WP_ADMIN_PASSWORD || "password";
+  const adminEmail = process.env.WP_ADMIN_EMAIL || "admin@localhost.com";
   const fields = new URLSearchParams({
     language: "en",
     prefix: "wp_",
     weblog_title: "My WordPress Website",
-    user_name: "admin",
-    admin_password: "password",
-    admin_password2: "password",
+    user_name: adminUser,
+    admin_password: adminPassword,
+    admin_password2: adminPassword,
     Submit: "Install WordPress",
     pw_weak: "1",
-    admin_email: "admin@localhost.com"
+    admin_email: adminEmail
   });
   return requestHandler.request({
     url: "/wp-admin/install.php?step=2",
@@ -175,8 +190,8 @@ var DEFAULT_WORDPRESS_VERSION = "latest";
 var DOCROOT = "/wordpress";
 
 // src/download.ts
-import fs9 from "fs";
-import path8 from "path";
+import fs10 from "fs";
+import path9 from "path";
 
 // src/detect/has-index-file.ts
 import fs from "fs";
@@ -188,7 +203,7 @@ function hasIndexFile(projectPath) {
 // src/detect/is-valid-wordpress-version.ts
 function isValidWordPressVersion(version) {
   const versionPattern = /^latest$|^(?:(\d+)\.(\d+)(?:\.(\d+))?)((?:-beta(?:\d+)?)|(?:-RC(?:\d+)?))?$/;
-  const classicPressPattern = /^classicpress(?:-(\d+)\.(\d+)(?:\.(\d+))?)?$/;
+  const classicPressPattern = /^classicpress(?:-(\d+)\.(\d+)(?:\.(\d+))?(?:-rc(?:\d+)?)?)?$/;
   return versionPattern.test(version) || classicPressPattern.test(version);
 }
 function isClassicPressVersion(version) {
@@ -253,13 +268,29 @@ function isThemeDirectory(projectPath) {
   return themeNameRegex.test(styleCSS);
 }
 
-// src/detect/is-wp-content-directory.ts
+// src/detect/is-wp-app-project.ts
 import fs5 from "fs";
 import path4 from "path";
+function isWpAppProject(projectPath) {
+  const composerJsonPath = path4.join(projectPath, "composer.json");
+  if (!fs5.existsSync(composerJsonPath)) {
+    return false;
+  }
+  try {
+    const composerJson = JSON.parse(fs5.readFileSync(composerJsonPath, "utf8"));
+    return composerJson.type === "wp-app";
+  } catch {
+    return false;
+  }
+}
+
+// src/detect/is-wp-content-directory.ts
+import fs6 from "fs";
+import path5 from "path";
 function isWpContentDirectory(projectPath) {
-  const muPluginsExists = fs5.existsSync(path4.join(projectPath, "mu-plugins"));
-  const pluginsExists = fs5.existsSync(path4.join(projectPath, "plugins"));
-  const themesExists = fs5.existsSync(path4.join(projectPath, "themes"));
+  const muPluginsExists = fs6.existsSync(path5.join(projectPath, "mu-plugins"));
+  const pluginsExists = fs6.existsSync(path5.join(projectPath, "plugins"));
+  const themesExists = fs6.existsSync(path5.join(projectPath, "themes"));
   if (muPluginsExists || pluginsExists || themesExists) {
     return true;
   }
@@ -267,29 +298,24 @@ function isWpContentDirectory(projectPath) {
 }
 
 // src/detect/is-wordpress-directory.ts
-import fs6 from "fs";
-import path5 from "path";
+import fs7 from "fs";
+import path6 from "path";
 function isWordPressDirectory(projectPath) {
-  return fs6.existsSync(path5.join(projectPath, "wp-content")) && fs6.existsSync(path5.join(projectPath, "wp-includes")) && fs6.existsSync(path5.join(projectPath, "wp-load.php"));
+  return fs7.existsSync(path6.join(projectPath, "wp-content")) && fs7.existsSync(path6.join(projectPath, "wp-includes")) && fs7.existsSync(path6.join(projectPath, "wp-load.php"));
 }
 
-// src/detect/is-wordpress-develop-directory.ts
-import fs7 from "fs";
-import path6 from "path";
-function isWordPressDevelopDirectory(projectPath) {
-  const requiredFiles = [
-    "src",
-    "src/wp-content",
-    "src/wp-includes",
-    "src/wp-load.php",
-    "build",
-    "build/wp-content",
-    "build/wp-includes",
-    "build/wp-load.php"
-  ];
-  return requiredFiles.every(
-    (file) => fs7.existsSync(path6.join(projectPath, file))
-  );
+// src/detect/is-classicpress-directory.ts
+import fs8 from "fs";
+import path7 from "path";
+function isClassicPressDirectory(projectPath) {
+  if (!isWordPressDirectory(projectPath)) {
+    return false;
+  }
+  const versionFile = path7.join(projectPath, "wp-includes", "version.php");
+  if (!fs8.existsSync(versionFile)) {
+    return false;
+  }
+  return fs8.readFileSync(versionFile, "utf8").includes("classicpress_version");
 }
 
 // src/output.ts
@@ -300,24 +326,54 @@ var output = shouldOutput() ? console : null;
 
 // src/paths.ts
 import crypto from "crypto";
-import fs8 from "fs";
+import fs9 from "fs";
 import os from "os";
-import path7 from "path";
+import path8 from "path";
 function getWpAppHome() {
-  return process.env[WP_APP_HOME_ENV] || path7.join(os.homedir(), WP_APP_HIDDEN_FOLDER);
+  const home = process.env[WP_APP_HOME_ENV] || path8.join(os.homedir(), WP_APP_HIDDEN_FOLDER);
+  cleanupLegacyHome(home);
+  return home;
 }
 function getCachePath() {
-  return ensureDir(path7.join(getWpAppHome(), "cache"));
+  return ensureDir(path8.join(getWpAppHome(), "cache"));
+}
+function getCorePath(wordPressVersion) {
+  const key = wordPressVersion.replace(/[^a-zA-Z0-9.-]/g, "_");
+  return path8.join(getWpAppHome(), "core", key);
 }
 function getSitePath(projectPath) {
-  const projectName = path7.basename(path7.resolve(projectPath));
-  const hash = crypto.createHash("sha1").update(path7.resolve(projectPath)).digest("hex");
-  return path7.join(getWpAppHome(), "sites", `${projectName}-${hash}`);
+  const resolved = path8.resolve(projectPath);
+  const identity = process.platform === "win32" ? resolved.toLowerCase() : resolved;
+  const projectName = path8.basename(resolved);
+  const hash = crypto.createHash("sha1").update(identity).digest("hex");
+  return path8.join(getWpAppHome(), "sites", `${projectName}-${hash}`);
+}
+function getProjectLocalPath(projectPath) {
+  return path8.join(path8.resolve(projectPath), ".local", "wp-app");
 }
 function ensureDir(dir) {
-  fs8.mkdirSync(dir, { recursive: true });
+  fs9.mkdirSync(dir, { recursive: true });
   return dir;
 }
+var LEGACY_TOP_LEVEL_DIRS = [
+  "wordpress-versions",
+  "wp-content",
+  "mu-plugins",
+  "sqlite-database-integration-main"
+];
+var legacyCleanupDone = false;
+function cleanupLegacyHome(home) {
+  if (legacyCleanupDone) {
+    return;
+  }
+  legacyCleanupDone = true;
+  for (const name of LEGACY_TOP_LEVEL_DIRS) {
+    const dir = path8.join(home, name);
+    if (fs9.existsSync(dir)) {
+      fs9.rmSync(dir, { recursive: true, force: true });
+    }
+  }
+}
 
 // src/download.ts
 function getWordPressVersionUrl(version) {
@@ -336,8 +392,8 @@ function getClassicPressVersionUrl(version) {
   return `https://github.com/ClassicPress/ClassicPress-release/archive/refs/tags/${tag}.zip`;
 }
 async function cachedZip(url, cacheKey) {
-  const cacheFile = path8.join(getCachePath(), cacheKey);
-  if (!fs9.existsSync(cacheFile)) {
+  const cacheFile = path9.join(getCachePath(), cacheKey);
+  if (!fs10.existsSync(cacheFile)) {
     output?.log(`Downloading ${cacheKey}...`);
     const response = await fetch(url, { redirect: "follow" });
     if (!response.ok) {
@@ -346,11 +402,11 @@ async function cachedZip(url, cacheKey) {
       );
     }
     const bytes = Buffer.from(await response.arrayBuffer());
-    fs9.writeFileSync(`${cacheFile}.partial`, bytes);
-    fs9.renameSync(`${cacheFile}.partial`, cacheFile);
+    fs10.writeFileSync(`${cacheFile}.partial`, bytes);
+    fs10.renameSync(`${cacheFile}.partial`, cacheFile);
     output?.log(`Cached ${cacheKey} (${bytes.length} bytes).`);
   }
-  return new File([fs9.readFileSync(cacheFile)], cacheKey);
+  return new File([fs10.readFileSync(cacheFile)], cacheKey);
 }
 async function getCoreZip(version) {
   if (isClassicPressVersion(version)) {
@@ -364,17 +420,22 @@ async function getSqliteIntegrationZip() {
 
 // src/engine.ts
 async function startWPApp(options) {
-  const projectPath = path9.resolve(options.projectPath);
+  const projectPath = path10.resolve(options.projectPath);
   const mode = options.mode;
   output?.log(`directory: ${options.projectPath}`);
   output?.log(`mode: ${mode}`);
   output?.log(`php: ${options.phpVersion}`);
-  const hostDocroot = mode === "index" /* INDEX */ || mode === "wordpress" /* WORDPRESS */ ? projectPath : mode === "wordpress-develop" /* WORDPRESS_DEVELOP */ ? path9.join(projectPath, "build") : ensureDir(getSitePath(projectPath));
+  const sharesCore = mode === "wp-app" /* WP_APP */ || mode === "theme" /* THEME */ || mode === "plugin" /* PLUGIN */ || mode === "wp-content" /* WP_CONTENT */;
+  const hostDocroot = mode === "index" /* INDEX */ || mode === "wordpress" /* WORDPRESS */ || mode === "classicpress" /* CLASSICPRESS */ ? projectPath : ensureDir(getCorePath(options.wordPressVersion));
+  const projectDataRoot = sharesCore ? ensureDir(
+    mode === "wp-app" /* WP_APP */ ? getProjectLocalPath(projectPath) : getSitePath(projectPath)
+  ) : null;
   const isWordPressBacked = mode !== "index" /* INDEX */;
-  const freshSite = isWordPressBacked && !fs10.existsSync(path9.join(hostDocroot, "wp-load.php"));
+  const freshCore = isWordPressBacked && !fs11.existsSync(path10.join(hostDocroot, "wp-load.php"));
+  const freshSite = sharesCore ? !fs11.existsSync(path10.join(projectDataRoot, "database", ".ht.sqlite")) : freshCore;
   if (isWordPressBacked) {
     output?.log(`wp: ${options.wordPressVersion}`);
-    output?.log(`site data: ${hostDocroot}`);
+    output?.log(`site data: ${projectDataRoot ?? hostDocroot}`);
   }
   const php = await createPhp(options.phpVersion);
   php.mkdir(DOCROOT);
@@ -384,7 +445,7 @@ async function startWPApp(options) {
     DOCROOT,
     options.absoluteUrl
   );
-  if (freshSite) {
+  if (freshCore) {
     await installCore(
       php,
       await getCoreZip(options.wordPressVersion),
@@ -399,6 +460,22 @@ async function startWPApp(options) {
         DOCROOT
       );
     }
+  }
+  if (projectDataRoot) {
+    const databaseDir = ensureDir(path10.join(projectDataRoot, "database"));
+    const uploadsDir = ensureDir(path10.join(projectDataRoot, "uploads"));
+    php.mkdir(`${DOCROOT}/wp-content/database`);
+    await php.mount(
+      `${DOCROOT}/wp-content/database`,
+      createNodeFsMountHandler(databaseDir)
+    );
+    php.mkdir(`${DOCROOT}/wp-content/uploads`);
+    await php.mount(
+      `${DOCROOT}/wp-content/uploads`,
+      createNodeFsMountHandler(uploadsDir)
+    );
+  }
+  if (isWordPressBacked) {
     defineSiteConstants(
       php,
       options.absoluteUrl,
@@ -415,8 +492,9 @@ async function startWPApp(options) {
   return { requestHandler, php, options, freshSite };
 }
 async function applyProjectMounts(php, mode, projectPath) {
-  const projectName = path9.basename(projectPath);
+  const projectName = path10.basename(projectPath);
   switch (mode) {
+    case "wp-app" /* WP_APP */:
     case "theme" /* THEME */:
       await mountAt(
         php,
@@ -432,13 +510,13 @@ async function applyProjectMounts(php, mode, projectPath) {
       );
       break;
     case "wp-content" /* WP_CONTENT */:
-      for (const entry of fs10.readdirSync(projectPath)) {
+      for (const entry of fs11.readdirSync(projectPath)) {
         if (entry === "index.php") {
           continue;
         }
         await mountAt(
           php,
-          path9.join(projectPath, entry),
+          path10.join(projectPath, entry),
           `${DOCROOT}/wp-content/${entry}`
         );
       }
@@ -448,14 +526,14 @@ async function applyProjectMounts(php, mode, projectPath) {
   }
 }
 async function mountAt(php, hostPath, vfsPath) {
-  if (fs10.statSync(hostPath).isDirectory()) {
+  if (fs11.statSync(hostPath).isDirectory()) {
     php.mkdir(vfsPath);
   }
   await php.mount(vfsPath, createNodeFsMountHandler(hostPath));
 }
 async function activateProject(php, mode, projectPath) {
-  const projectName = path9.basename(projectPath);
-  if (mode === "theme" /* THEME */) {
+  const projectName = path10.basename(projectPath);
+  if (mode === "wp-app" /* WP_APP */ || mode === "theme" /* THEME */) {
     await runWordPressCode(
       php,
       `switch_theme(${phpString(projectName)});`
@@ -500,11 +578,11 @@ function phpString(value) {
 }
 function findPluginFile(projectPath) {
   const pluginNameRegex = /^(?:[ \t]*<\?php)?[ \t/*#@]*Plugin Name:(.*)$/im;
-  for (const file of fs10.readdirSync(projectPath)) {
+  for (const file of fs11.readdirSync(projectPath)) {
     if (!file.endsWith(".php")) {
       continue;
     }
-    const content = fs10.readFileSync(path9.join(projectPath, file), "utf8");
+    const content = fs11.readFileSync(path10.join(projectPath, file), "utf8");
     if (pluginNameRegex.test(content)) {
       return file;
     }
@@ -512,8 +590,10 @@ function findPluginFile(projectPath) {
   return null;
 }
 function inferMode(projectPath) {
-  if (isWordPressDevelopDirectory(projectPath)) {
-    return "wordpress-develop" /* WORDPRESS_DEVELOP */;
+  if (isWpAppProject(projectPath)) {
+    return "wp-app" /* WP_APP */;
+  } else if (isClassicPressDirectory(projectPath)) {
+    return "classicpress" /* CLASSICPRESS */;
   } else if (isWordPressDirectory(projectPath)) {
     return "wordpress" /* WORDPRESS */;
   } else if (isWpContentDirectory(projectPath)) {
@@ -525,7 +605,7 @@ function inferMode(projectPath) {
   } else if (hasIndexFile(projectPath)) {
     return "index" /* INDEX */;
   }
-  return "playground" /* PLAYGROUND */;
+  return null;
 }
 
 // src/port-finder.ts
@@ -556,11 +636,6 @@ var PortFinder = class _PortFinder {
       });
     });
   }
-  /**
-   * Returns the first available open port, caching and reusing it for subsequent calls.
-   *
-   * @returns {Promise<number>} A promise that resolves to the open port number.
-   */
   async getOpenPort() {
     if (this.#openPort) {
       return this.#openPort;
@@ -612,7 +687,11 @@ async function getWpAppConfig(args) {
     }
   });
   if (!options.mode || options.mode === "auto") {
-    options.mode = inferMode(options.projectPath);
+    const inferred = inferMode(options.projectPath);
+    if (!inferred) {
+      process.exit(1);
+    }
+    options.mode = inferred;
   }
   if (!options.absoluteUrl) {
     options.absoluteUrl = await getAbsoluteURL();
@@ -631,12 +710,12 @@ async function getWpAppConfig(args) {
 }
 
 // src/start-server.ts
-import fs11 from "fs";
+import fs12 from "fs";
 import { Readable } from "stream";
 import { pipeline } from "stream/promises";
 import express from "express";
 async function startServer(options = {}) {
-  if (!fs11.existsSync(options.projectPath)) {
+  if (!fs12.existsSync(options.projectPath)) {
     throw new Error(
       `The given path "${options.projectPath}" does not exist.`
     );