@ideasonpurpose/build-tools-wordpress 2.10.5 → 2.10.7

package/README.md

@@ -1,99 +1,281 @@
 # @ideasonpurpose/build-tools-wordpress
 
-#### Version 2.10.5
+#### Version 2.10.7
 
 [![NPM Version](https://img.shields.io/npm/v/%40ideasonpurpose%2Fbuild-tools-wordpress?logo=npm)](https://www.npmjs.com/package/@ideasonpurpose/build-tools-wordpress)
-[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/ideasonpurpose/build-tools-wordpress/npm-publish.yml?logo=github&logoColor=white)](https://github.com/ideasonpurpose/build-tools-wordpress#readme)
+[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/ideasonpurpose/build-tools-wordpress/npm-publish.yml?logo=github&logoColor=white)](https://github.com/ideasonpurpose/build-tools-wordpress/actions/workflows/npm-publish.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
 
-Build scripts and dependencies for IOP's WordPress development environments.
+Build scripts and shared dependencies for WordPress development. Used in production at [Ideas On Purpose](https://www.ideasonpurpose.com).
 
-## About This Package
+This package centralizes Webpack configuration, asset pipelines, and helper CLIs so host projects stay thin: a small `package.json`, a one-line `webpack.config.js`, and an optional config file.
 
-These tools were migrated from our [Docker-based WordPress build tools](https://github.com/ideasonpurpose/docker-build) to speed up development and began the process of moving our build tools away from webpack. Gathering dependencies also simplifies the package.json and configuration files in host projects, making those slightly more manageable.
+## Requirements
 
-### Versioned Releases
+- **Node.js** 22.15+ (required by webpack-dev-server 6; ESM only)
 
-IOP versions our themes so every release creates a clear rollback snapshot. To accomplish this, every milestone build is generated into a versioned directory. This works well for themes where only one can be active, but fails for plugins where multiple versions can be simultaneously enabled so long as their directory names are different.
+## Install
 
-To work around this, a `type` property can be added to the config file. When `type` is `plugin`, builds will not add the version to directory names.
+```sh
+npm install -D @ideasonpurpose/build-tools-wordpress
+```
 
-### Optional Config
+Typical host scripts (see [`boilerplate/package.json`](./boilerplate/package.json)):
 
-Each project may optionally include an **ideasonpurpose.config.js** file in the same directory as **package.json**. Any settings in this file will override [the defaults](https://github.com/ideasonpurpose/build-tools-wordpress/blob/main/config/ideasonpurpose.config.js).
+```json
+{
+  "type": "module",
+  "scripts": {
+    "prebuild": "npm run clean",
+    "build": "NODE_ENV=production webpack",
+    "postbuild": "npm run zip",
+    "start": "webpack serve",
+    "zip": "iop-build-zip-archive"
+  },
+  "devDependencies": {
+    "@ideasonpurpose/build-tools-wordpress": "^2.10.6"
+  },
+  "prettier": "@ideasonpurpose/prettier-config",
+  "stylelint": {
+    "extends": "@ideasonpurpose/stylelint-config"
+  }
+}
+```
 
-<!--
+Prettier and Stylelint configs are re-exported from this package’s dependencies so hosts can extend them without separate installs.
 
-- **`src`** - The **source** directory containing source files which should be compiled or transposed. The contents of this directory will be omitted from builds.
-- **`dist`** - The **distribution** directory where processed, production-ready files will be output to. All contents of this directory will be included in builds.
-- **`src`** - An array of file entry points relative to the `src` directory. Each entry point will generate a like-named output file. All files and assets imported by a given entry point will be accessible from that entry's corresponding output file.
+## Quick start
 
--->
+**1. Point Webpack at this package**
 
-## SVG Processing
+```js
+// webpack.config.js
+export { webpackConfig as default } from "@ideasonpurpose/build-tools-wordpress";
+```
 
-Webpack handles SVG files differently based on import context:
+**2. Lay out sources** under the default theme paths (package `name` → theme folder):
 
-- **In SCSS files**: SVGs referenced via `url('file.svg')` are inlined as data URIs if under 4KB, otherwise emitted as separate files in the output directory.
+```text
+wp-content/themes/<package-name>/
+  src/
+    js/main.js
+    js/admin.js
+    js/editor.js
+    sass/   # or styles/
+  dist/     # build output
+```
 
-- **In JS/TSX files**:
-  - With `?url` query (e.g., `import svg from 'file.svg?url'`): Treated as assets, inlined as data URIs if under 4KB, else files.
-  - With `?react` query (e.g., `import Icon from 'file.svg?react'`): Explicitly converted to a React component using `@svgr/webpack`.
-  - Without `?url` or `?react`: Converted to React components using `@svgr/webpack` for direct JSX usage (default behavior when imported from `.jsx`/`.tsx`).
+**3. Run**
 
-React components imported via `?react` (or implicitly) have `width`/`height` removed (`dimensions: false`), making them responsive while preserving `viewBox`.
+```sh
+npm start          # webpack-dev-server (proxies local WordPress when available)
+NODE_ENV=production npm run build   # production build + zip (if postbuild is set)
+```
 
-Data URIs are generated as `data:image/svg+xml,<url-encoded-content>` using more efficient URL-encoding, not base64.
+Full IOP projects also use Docker Compose tooling from this package (`tooling/docker-compose.yml`) and scripts like `bootstrap`, `db:dump`, and `project:refresh`. Those are optional if you only need the asset pipeline.
 
-### SVG Optimization
+## Configuration
 
-SVGO is included along with our preferred [svgo.config.mjs][]. Run this with `npx svgo <file-to-optimize.svg>`
+Optional config is loaded with [cosmiconfig](https://github.com/cosmiconfig/cosmiconfig) under the name `ideasonpurpose` — typically `ideasonpurpose.config.js` next to `package.json`. Values merge over [defaults](./lib/buildConfig.js).
 
-## Experimental formatting helpers
+### Defaults
 
-This package includes two experimental formatting scripts:
+| Option         | Default                                               | Notes                                                                            |
+| -------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `src`          | `./wp-content/themes/<name>/src`                      | `<name>` from host `package.json`                                                |
+| `dist`         | `./wp-content/themes/<name>/dist`                     |                                                                                  |
+| `entry`        | `["./js/main.js", "./js/admin.js", "./js/editor.js"]` | Relative to `src`. String, array, or object                                      |
+| `publicPath`   | `/wp-content/themes/<name>/dist/`                     |                                                                                  |
+| `esTarget`     | `"es2020"`                                            | Passed to esbuild-loader / minimizer                                             |
+| `devtool`      | `"source-map"`                                        |                                                                                  |
+| `proxy`        | `"wordpress"`                                         | Dev-server proxy target (Docker service name, URL, IP, or `true` to auto-detect) |
+| `manifestFile` | `"./dependency-manifest.json"`                        | Written into `dist`                                                              |
+| `type`         | _(unset / theme)_                                     | Set `"plugin"` to change archive naming                                          |
 
-### `iop-html-php-prettier`
+Paths resolve relative to the config file (or `package.json` if no config file is found).
 
-This uses [Prettier](https://prettier.io) to double-format mixed HTML and PHP files (like WordPress templates). PHP blocks are tokenized so Prettier can safely format the file as HTML, then PHP blocks are restored and the file is formatted again as PHP using [@prettier/plugin-php](https://github.com/prettier/plugin-php).
-**Usage:** `npx iop-html-php-prettier path/to/file.php`
+### Entry shapes
 
-### `iop-format-wp-block-pattern`
+```js
+// Array → basenames become entry keys (overlapping basenames merge)
+entry: ["./js/main.js", "./js/admin.js"];
+
+// String → single entry
+entry: "./js/main.js";
+
+// Object → passed through
+entry: { app: "./js/main.js", admin: "./js/admin.js" };
+```
+
+### Themes vs plugins
+
+Releases are versioned so each build is a clear rollback snapshot. For **themes**, zip archives use a versioned folder name (`my-theme-1.2.3`). That fails for **plugins**, where multiple versions can be active if directory names differ.
+
+Set `type: "plugin"` to omit the version from the archive directory name:
+
+```js
+// ideasonpurpose.config.js
+export default {
+  type: "plugin",
+  src: `./wp-content/plugins/my-plugin/src`,
+  dist: `./wp-content/plugins/my-plugin/dist`,
+  publicPath: `/wp-content/plugins/my-plugin/dist/`,
+  entry: ["./js/main.js"],
+};
+```
+
+## What the build does
+
+| Area       | Implementation                                                                                                                                                                                          |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Bundler    | Webpack 5                                                                                                                                                                                               |
+| JS/TS/JSX  | [esbuild-loader](https://github.com/privatenumber/esbuild-loader)                                                                                                                                       |
+| CSS        | Sass ([sass-embedded](https://sass-lang.com/dart-sass/), modern compiler API), PostCSS (autoprefixer; cssnano in production)                                                                            |
+| Images     | `asset` modules + [Sharp](https://sharp.pixelplumbing.com/) via image-minimizer-webpack-plugin                                                                                                          |
+| SVG        | Asset / data-URI or React components via [@svgr/webpack](https://react-svgr.com/) (see below)                                                                                                           |
+| Copy       | Static files from `src` (blocks, fonts, etc. handled specially)                                                                                                                                         |
+| WordPress  | [`@wordpress/dependency-extraction-webpack-plugin`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-dependency-extraction-webpack-plugin/) + custom dependency manifest |
+| Dev server | Hot reload, live reload on PHP/HTML/SVG/JSON, reverse proxy to local WP                                                                                                                                 |
+| Production | Content hashes, minification, optional bundle analyzer report, zip via `iop-build-zip-archive`                                                                                                          |
+
+Sass `loadPaths` include `src/sass`, `src/styles`, and the project `node_modules`, so packages can be imported by name:
+
+```scss
+@use "some-npm-package/styles";
+```
+
+### Dev server
+
+- Proxies the site to a local WordPress container (default Docker service name `wordpress`) when `proxy` is enabled
+- Watches theme PHP/HTML/SVG/JSON for full reload
+- `GET /webpack/reload` triggers a client refresh (useful from PHP or external tools)
+
+### Zip archives
+
+`iop-build-zip-archive` packs the theme/plugin parent of `src` into `_builds/<name>[-version].zip`. Version suffix is skipped when `type` is `"plugin"`.
+
+## SVG processing
+
+Webpack treats SVGs differently by context:
+
+- **In SCSS** (`url('file.svg')`): inlined as a data URI if under 4KB, otherwise emitted as a file.
+- **In JS/TSX**:
+  - `import svg from 'file.svg?url'` — asset URL / data URI (4KB threshold)
+  - `import Icon from 'file.svg?react'` — React component via SVGR
+  - bare `import Icon from 'file.svg'` from `.jsx`/`.tsx` — React component (default)
+
+React SVG components use `dimensions: false` (no fixed `width`/`height`; `viewBox` kept) so they scale with CSS.
 
-A specialized formatter for WordPress PHP block patterns. This makes block markup easier to read, expands JSON settings, and adjusts whitespace to work around Block Editor quirks.
-**Usage:** `npx iop-format-wp-block-pattern path/to/pattern.php`
+Data URIs use URL-encoding (`data:image/svg+xml,<encoded>`), not base64.
 
-## Local Development
+### SVGO and VS Code
 
-Because this project makes use of bin scripts, conventional `npm link` workflows won't work correctly. To work on this code in a development project, change the project's package.json to install from a local file path, probably something like this:
+[SVGO](https://github.com/svg/svgo) and our preferred [`config/svgo.config.mjs`](./config/svgo.config.mjs) ship with the package, plus a stdin formatter for the editor.
+
+Install [SVG Language Mode ID](https://marketplace.visualstudio.com/items?itemName=ideasonpurpose.svg-language-mode-id) and [Custom Local Formatters](https://marketplace.visualstudio.com/items?itemName=jkillian.custom-local-formatters), then in `settings.json`:
 
 ```json
-  "devDependencies": {
-    "@ideasonpurpose/build-tools-wordpress": "../../build-tools-wordpress"
+{
+  "[svg]": {
+    "editor.defaultFormatter": "jkillian.custom-local-formatters",
+    "editor.formatOnSave": false
+  },
+  "customLocalFormatters.formatters": [
+    {
+      "command": "iop-vscode-svgo",
+      "languages": ["svg"]
+    }
+  ]
+}
+```
+
+The formatter loads a project `svgo.config` if present, otherwise falls back to this package’s config.
+
+Notes:
+
+- VS Code treats SVG as XML by default; the language-mode extension is required for the `[svg]` scope.
+- Formatting fails if `editor.formatOnSaveMode` is `"modifications"` (range formatting does not send a full document).
+
+**IOP SVGO defaults** ([`config/svgo.config.mjs`](./config/svgo.config.mjs)):
+
+- Pretty-print with 4-space indent
+- Preserve ID names (`cleanupIds: false`)
+- Custom: copy width/height from `viewBox` onto `<svg>` when missing
+- Custom: remove top-level `fill="none"`
+- `removeUselessStrokeAndFill` with `removeNone: true`
+
+## CLI tools
+
+| Command                       | Purpose                                                                                                                                                                                 |
+| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `iop-build-zip-archive`       | Zip theme/plugin into `_builds/`                                                                                                                                                        |
+| `iop-build-port-reporter`     | Print discovered local WordPress URL/port (Docker)                                                                                                                                      |
+| `iop-project-refresh`         | Sync host tooling from package boilerplate (`package.json` scripts, `docker-compose.yml`, `.gitignore`, dirs, optional templates). Flags: `--dry-run`, `--force` (allow dirty git tree) |
+| `iop-html-php-prettier`       | Experimental mixed HTML/PHP formatter                                                                                                                                                   |
+| `iop-format-wp-block-pattern` | Experimental WordPress block-pattern PHP formatter                                                                                                                                      |
+| `iop-vscode-svgo`             | SVGO over stdin for editor formatters                                                                                                                                                   |
+
+### `iop-html-php-prettier`
+
+Double-formats mixed HTML and PHP (WordPress templates): PHP is tokenized, the file is formatted as HTML with Prettier, tokens are restored, then PHP is formatted with [@prettier/plugin-php](https://github.com/prettier/plugin-php).
+
+A faster rewrite is in progress: **[Format Mixed PHP and HTML](https://github.com/ideasonpurpose/format-mixed-php-html)**.
+
+```sh
+npx iop-html-php-prettier path/to/file.php
+```
+
+Also accepts STDIN → STDOUT for Custom Local Formatters:
+
+```json
+"customLocalFormatters.formatters": [
+  {
+    "command": "npx iop-html-php-prettier",
+    "languages": ["php"]
   }
+]
 ```
 
-Running a simple watch script to re-install on changes will make things somewhat seamless:
+### `iop-format-wp-block-pattern`
+
+Formats WordPress block pattern PHP: readable block markup, expanded JSON in `<!-- wp:... -->` comments, and whitespace tuned for the block editor.
 
 ```sh
-cd dev-project-working-dir
-npm chokidar-cli "../../build-tools-wordpress/**/*" -c "npm install"
+npx iop-format-wp-block-pattern path/to/pattern.php
 ```
 
-### Additional Notes
+### `iop-project-refresh`
 
-This project expects an entirely ES Module based environment and specifies all dependencies using standard ESM import syntax. Projects importing this file should set `"type": "module"` in their package.json files.
+Updates an existing project’s tooling from this package’s `boilerplate/` and `tooling/` trees. Safe defaults: refuses a dirty git working tree unless `--force`; use `--dry-run` to preview.
 
-#### Sass imports
+```sh
+npx iop-project-refresh
+npx iop-project-refresh --dry-run
+npx iop-project-refresh --force
+```
 
-Sass can import stylesheet files directly from npm packages. Use the full path from node_modules like this:
+## Local development (this package)
 
-```scss
-@use "@ideasonpurpose/build-tools-wordpress/example/package-style";
+Bin scripts break conventional `npm link`. In a consumer project, depend on a local path instead:
+
+```json
+"devDependencies": {
+  "@ideasonpurpose/build-tools-wordpress": "file:../../build-tools-wordpress"
+}
+```
+
+Reinstall on change:
+
+```sh
+cd dev-project-working-dir
+npx chokidar-cli "../../build-tools-wordpress/**/*" -c "npm install"
 ```
 
-#### Publishing to [npm](https://www.npmjs.com/package/@ideasonpurpose/build-tools-wordpress)
+## Publishing
+
+Version-tagged releases publish to npm via GitHub Actions (OIDC trusted publishing). See [CHANGELOG.md](./CHANGELOG.md).
 
-A GitHub action will auto-publish version-tagged releases to npm. In order to publish, the repository must have an `NPM_TOKEN` secret set with the token from npm. [Log into npmjs.org](https://www.npmjs.com/login) with a publish-authorized account, then find the token page linked from the Profile page sidebar. Generate a new token and update the repository secret.
+If the workflow needs a classic token instead, set repository secret `NPM_TOKEN` from an npm publish-capable account.
 
 <!-- START IOP CREDIT BLURB 2026-07-->
 
@@ -102,6 +284,6 @@ A GitHub action will auto-publish version-tagged releases to npm. In order to pu
 #### Brought to you by IOP
 
 | <a href="https://www.ideasonpurpose.com"><img src="https://raw.githubusercontent.com/ideasonpurpose/ideasonpurpose/master/iop-logo-white-on-black-88px.png" width="44" height="44" align="top" alt="IOP Logo"></a> <br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | This project is actively developed and used in production at <a href="https://www.ideasonpurpose.com">Ideas On Purpose</a>. <br>&nbsp; |
-| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
 
 <!-- END IOP CREDIT BLURB -->

package/bin/format-php-prettier.js

@@ -2,6 +2,9 @@
 
 //@ts-check
 
+import prettierConfig from "@ideasonpurpose/prettier-config" with {
+  type: "json",
+};
 /**
  * This is an experimental proof-of-concept for formatting mixed HTML & PHP
  * files from a single function.
@@ -9,15 +12,17 @@
  * TODO: Testing, naming, modularization, VS Code extension
  */
 import prettier from "prettier";
-import prettierConfig from "@ideasonpurpose/prettier-config" with { type: "json" };
 
 const phpPlugin = await import("@prettier/plugin-php");
 
 // Explicitly reset the plugin because global installs can't resolve it
+// @ts-expect-error — prettierConfig types expect string paths, but runtime accepts plugin modules
 prettierConfig.plugins = [phpPlugin];
 
-import { readFile, writeFile } from "fs/promises";
-import { resolve, basename } from "path";
+import { realpathSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import { basename, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 
 /**
  * Prettier API doesn't recognize overrides, so we extract them
@@ -30,6 +35,7 @@ const phpOptions = prettierConfig.overrides.find(
   (o) => o.files === "*.php",
 )?.options;
 
+/** @param {string} html @param {number} offset */
 const isInTag = (html, offset) => {
   if (offset === 0) return false;
 
@@ -56,6 +62,7 @@ const isInTag = (html, offset) => {
  * being mutilated by the HTML formatting step. Cleaner than adding a string.replace
  * to unTokenizeHTML().
  */
+/** @param {string} htmlContent */
 export function tokenizeHTML(htmlContent) {
   let tokenizedHTML = "";
   const phpCodeBlocks = new Map(); // Changed to Map for better performance and type safety
@@ -67,6 +74,7 @@ export function tokenizeHTML(htmlContent) {
    *
    * NOTE: This uses tokenCount from the enclosing scope
    */
+  /** @param {string} phpCodeBlock @param {string} prevContent */
   const tokenizeCodeBlock = (phpCodeBlock, prevContent) => {
     let start = "<";
     let end = " />";
@@ -79,27 +87,14 @@ export function tokenizeHTML(htmlContent) {
     return `${start}php_${tokenCount++}__`.padEnd(codeLength, "_") + end;
   };
 
-  // const pattern = /<\?(?:php|=)[\s\S]*?\?>/gs;
-  // const pattern =
-  //   /(?<before>(?:[^\s]|\s|^)\s*)(?<php><\?(?:php|=).*?(?:\?>|$))(?<after>(?:\s*)[^\s]|$)/gs;
-  // const pattern =
-  //   /((?:[^\s]|\s|^)\s*)(<\?(?:php|=).*?(?:\?>|$))((?:\s*)[^\s]|$)/gms;
-  // // const pattern = /([^\s]+)\s*(<\?(?:php|=).*?(?:\?>|$))\s*([^\s]*)/gms;
-  // const pattern =
-  //   /([^\s]?\s*)?(<\?(?:php|=).*?(?:\?>|$))((?:\s*)[^\s]|$)/gms;
-  // const pattern =
-  //   /(?<=((?:[^\s]|\s|^)\s*))(<\?(?:php|=).*?\?>)(?=((?:\s*)[^\s]|$))/gms;
-  // try removing look ahead/behind
-  const pattern = /(<\?(?:php|=).*?\?>)/gms;
-
   // const regex = new RegExp(/<\?(?:php|=).*?\?>/, "gs");
   // Trying to capture open-ended PHP codeBlocks in a single regexp
   const regex = new RegExp(/<\?(?:php|=).*?(?:\?>|$)/, "gs");
 
-  let match;
+  let match = regex.exec(htmlContent);
   let token;
   let lastIndex = 0;
-  while ((match = regex.exec(htmlContent)) !== null) {
+  while (match !== null) {
     tokenizedHTML += htmlContent.slice(lastIndex, match.index);
 
     token = tokenizeCodeBlock(match[0], tokenizedHTML);
@@ -107,12 +102,14 @@ export function tokenizeHTML(htmlContent) {
     tokenizedHTML += token;
 
     lastIndex = match.index + match[0].length;
+    match = regex.exec(htmlContent);
   }
   tokenizedHTML += htmlContent.slice(lastIndex);
 
   return { tokenizedHTML, phpCodeBlocks };
 }
 
+/** @param {string} tokenizedHTML @param {Map<string, string>} phpCodeBlocks */
 export function unTokenizeHTML(tokenizedHTML, phpCodeBlocks) {
   let phpContent = tokenizedHTML;
   for (const [token, phpBlock] of phpCodeBlocks) {
@@ -132,55 +129,129 @@ export function unTokenizeHTML(tokenizedHTML, phpCodeBlocks) {
 }
 
 /**
- * Formats a mixed HTML & PHP file with these steps:
+ * @param {bigint} start
+ * @param {bigint} end
+ */
+const ms = (start, end) => Number(end - start) / 1e6;
+
+/**
+ * Formats mixed HTML & PHP content:
  *  1. Tokenize PHP Blocks as HTML-safe and attribute-safe strings
  *  2. Format the result as HTML
  *  3. Un-tokenize HTML back to PHP
  *  4. Format again as PHP
- *  5. Overwrite the file
  *
- * @param {string} filepath - The path to the file to format (must be a valid file path).
+ * @param {string} content
+ * @param {string} [label]
+ * @returns {Promise<string>}
  */
-export async function formatHTMLThenPHP(filepath) {
-  try {
-    const startTime = process.hrtime.bigint();
-    const rawFile = await readFile(filepath, "utf8");
+export async function formatHTMLThenPHPContent(content, label = "stdin") {
+  const t0 = process.hrtime.bigint();
+  const startupMs = process.uptime() * 1e3;
 
-    const { tokenizedHTML, phpCodeBlocks } = tokenizeHTML(rawFile);
+  const tTokenize0 = process.hrtime.bigint();
+  const { tokenizedHTML, phpCodeBlocks } = tokenizeHTML(content);
+  const tTokenize1 = process.hrtime.bigint();
 
-    const htmlFormatted = await prettier.format(tokenizedHTML, {
-      ...prettierConfig,
-      ...htmlOptions,
-      parser: "html",
-      embeddedLanguageFormatting: "auto",
-    });
+  const htmlFormatted = await prettier.format(tokenizedHTML, {
+    ...prettierConfig,
+    ...htmlOptions,
+    parser: "html",
+    embeddedLanguageFormatting: "auto",
+  });
+  const tHtml = process.hrtime.bigint();
 
-    const phpUnTokenized = unTokenizeHTML(htmlFormatted, phpCodeBlocks);
+  const phpUnTokenized = unTokenizeHTML(htmlFormatted, phpCodeBlocks);
+  const tUnTokenize = process.hrtime.bigint();
 
-    const phpFormatted = await prettier.format(phpUnTokenized, {
-      ...prettierConfig,
-      ...phpOptions,
-      parser: "php",
-      embeddedLanguageFormatting: "auto",
-      // plugins: [phpPlugin], // Explicitly pass the plugin
-    });
+  const phpFormatted = await prettier.format(phpUnTokenized, {
+    ...prettierConfig,
+    ...phpOptions,
+    parser: "php",
+    embeddedLanguageFormatting: "auto",
+  });
+  const tEnd = process.hrtime.bigint();
 
-    await writeFile(filepath, phpFormatted, "utf8");
-    const endTime = process.hrtime.bigint();
-    const duration = Number(endTime - startTime);
+  console.error(
+    [
+      label,
+      `startup ${startupMs.toFixed(2)}ms`,
+      `tokenize ${ms(tTokenize0, tTokenize1).toFixed(2)}ms`,
+      `formatHTML ${ms(tTokenize1, tHtml).toFixed(2)}ms`,
+      `unTokenize ${ms(tHtml, tUnTokenize).toFixed(2)}ms`,
+      `formatPHP ${ms(tUnTokenize, tEnd).toFixed(2)}ms`,
+      `total ${(startupMs + ms(t0, tEnd)).toFixed(2)}ms`,
+    ].join("  "),
+  );
 
-    console.log(`${basename(filepath)} ${(duration / 1e6).toFixed(2)}ms`);
-  } catch (error) {
-    console.error("Error:", error);
+  return phpFormatted;
+}
+
+/**
+ * Formats a mixed HTML & PHP file in place.
+ *
+ * @param {string} filepath
+ */
+export async function formatHTMLThenPHP(filepath) {
+  const rawFile = await readFile(filepath, "utf8");
+  const phpFormatted = await formatHTMLThenPHPContent(
+    rawFile,
+    basename(filepath),
+  );
+  await writeFile(filepath, phpFormatted, "utf8");
+}
+
+/**
+ * @returns {Promise<string>}
+ */
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
   }
+  return Buffer.concat(chunks).toString("utf8");
 }
 
+/**
+ * CLI: filepath arg overwrites the file; no arg reads STDIN and writes STDOUT.
+ *
+ * @param {string} [filepath]
+ */
 export async function main(filepath = process.argv[2]) {
-  if (!filepath) {
-    console.error("Error: A filepath is required.");
-    return;
+  try {
+    if (filepath) {
+      await formatHTMLThenPHP(resolve(filepath));
+      return;
+    }
+
+    if (process.stdin.isTTY) {
+      console.error(
+        "Usage: iop-html-php-prettier <filepath>\n       iop-html-php-prettier < input.php",
+      );
+      process.exitCode = 1;
+      return;
+    }
+
+    const formatted = await formatHTMLThenPHPContent(
+      await readStdin(),
+      "stdin",
+    );
+    process.stdout.write(formatted);
+  } catch (error) {
+    console.error("Error:", error);
+    process.exitCode = 1;
   }
-  await formatHTMLThenPHP(resolve(filepath));
 }
 
-if (process.argv[2]) main();
+const isMain = (() => {
+  if (process.argv[1] == null) return false;
+  try {
+    return (
+      fileURLToPath(import.meta.url) === realpathSync(resolve(process.argv[1]))
+    );
+  } catch {
+    return false;
+  }
+})();
+
+if (isMain) main();

package/bin/vscode-svgo.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+
+// @ts-check
+
+import { readFileSync } from "node:fs";
+import { loadConfig, optimize } from "svgo";
+import fallbackConfig from "../config/svgo.config.mjs";
+
+console.error("starting iop-vscode-svgo");
+
+if (process.stdin.isTTY) {
+  process.stderr.write("Error: No SVG data received on stdin\n");
+  process.exit(1);
+}
+
+const svg = readFileSync(0, "utf8").trim();
+if (!svg) {
+  process.stderr.write("Error: No SVG data received on stdin\n");
+  process.exit(1);
+}
+
+try {
+  const svgoConfig = /** @type {import("svgo").Config} */ (
+    (await loadConfig()) ?? fallbackConfig
+  );
+  const result = optimize(svg, svgoConfig);
+  process.stdout.write(result.data);
+} catch (err) {
+  process.stderr.write(`Error: ${err instanceof Error ? err.message : err}\n`);
+  process.exit(1);
+}
+console.error("Done!");

package/bin/zip.js

@@ -15,6 +15,7 @@ import { globby } from "globby";
 import isTextPath from "is-text-path";
 import replaceStream from "replacestream";
 import stringLength from "string-length";
+import open from "open";
 
 import { buildConfig } from "../index.js";
 import { prettierHrtime } from "../lib/prettier-hrtime.js";
@@ -181,7 +182,7 @@ function foundReporter(file) {
   }
 }
 
-function finishReporter() {
+async function finishReporter() {
   const outBytes = archive.pointer();
   const end = process.hrtime(start);
   const duration = prettierHrtime(end);
@@ -225,4 +226,7 @@ function finishReporter() {
     chalk.bold(`Remember to push to ${chalk.cyan("GitHub!")}`),
   );
   console.log("✨");
+
+  // Experiment: Try opening the _builds directory at the end of the build
+  await open(dirname(zipFile.pathname));
 }

package/biome.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.5.6/schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "files": {
+    "ignoreUnknown": false
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space"
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "preset": "recommended",
+      "a11y": {
+        "noSvgWithoutTitle": "off"
+      },
+      "style": {
+        "useNodejsImportProtocol": {
+          "level": "error",
+          "fix": "safe"
+        }
+      }
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "double"
+    }
+  },
+  "assist": {
+    "enabled": true,
+    "actions": {
+      "source": {
+        "organizeImports": "on"
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ideasonpurpose/build-tools-wordpress",
-  "version": "2.10.5",
+  "version": "2.10.7",
   "description": "Build scripts and dependencies for IOP's WordPress development environments.",
   "homepage": "https://github.com/ideasonpurpose/build-tools-wordpress#readme",
   "bugs": {
@@ -23,14 +23,15 @@
     "iop-build-zip-archive": "./bin/zip.js",
     "iop-html-php-prettier": "./bin/format-php-prettier.js",
     "iop-format-wp-block-pattern": "./bin/format-wp-block-pattern.js",
-    "iop-project-refresh": "./bin/refresh.js"
+    "iop-project-refresh": "./bin/refresh.js",
+    "iop-vscode-svgo": "./bin/vscode-svgo.js"
   },
   "directories": {
     "lib": "lib"
   },
   "scripts": {
     "test": "vitest",
-    "version": "version-everything && auto-changelog && git add -u"
+    "version": "version-everything && git add -u"
   },
   "prettier": "@ideasonpurpose/prettier-config",
   "dependencies": {
@@ -67,6 +68,7 @@
     "is-text-path": "^3.0.0",
     "lodash": "^4.18.1",
     "mini-css-extract-plugin": "^2.10.2",
+    "open": "^11.0.0",
     "ora": "^9.4.1",
     "postcss": "^8.5.19",
     "postcss-loader": "^8.2.1",
@@ -88,12 +90,10 @@
     "version-everything": "^0.12.2",
     "webpack": "^5.108.4",
     "webpack-bundle-analyzer": "^5.3.1",
+    "webpack-cli": "^6.0.1",
     "webpack-dev-server": "^6.0.0",
     "webpack-manifest-plugin": "^6.0.1"
   },
-  "peerDependencies": {
-    "webpack-cli": "^6.0.1"
-  },
   "engines": {
     "node": ">=22.15.0"
   },

package/CHANGELOG.md

@@ -1,513 +0,0 @@
-### Changelog
-
-All notable changes to this project will be documented in this file. Dates are displayed in UTC.
-
-Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
-
-#### v2.10.4
-
-> 18 July 2026
-
-- fix zip reporting and resolve typescript types
-
-#### v2.10.3
-
-> 17 July 2026
-
-- More reporter tweaks
-
-#### v2.10.2
-
-> 16 July 2026
-
-- tweak reporting
-
-#### v2.10.1
-
-> 15 July 2026
-
-- remove infrastructureLogging
-
-#### v2.10.0
-
-> 15 July 2026
-
-- bump deps, AGENTS
-- update proxy, messing with output
-- add discard-changes config to example composer.json
-
-#### v2.9.1
-
-> 26 June 2026
-
-- bump deps, format action
-
-#### v2.9.0
-
-> 26 June 2026
-
-- update AGENTS
-- strip dimensions from React-imported SVGRs.
-
-#### v2.8.5
-
-> 23 June 2026
-
-- simplify release workflow
-- suppress GTID warnings from mysqldump
-
-#### v2.8.4
-
-> 23 June 2026
-
-- bump deps
-- update SVGO config plus custom plugins
-- extend whitespace handling to paragraphs with attributes
-
-#### v2.8.3
-
-> 5 June 2026
-
-- make formatting conditionals work with npx again
-- add WP_ENVIRONMENT_TYPE to docker-compose environment
-
-#### v2.8.2
-
-> 3 June 2026
-
-- update zip script to use ESM archiver
-
-#### v2.8.1
-
-> 3 June 2026
-
-- fix db connection checks in docker-compose
-
-#### v2.8.0
-
-> 3 June 2026
-
-- bump deps
-- refactor format functions and improve tests
-- boilerplate and README SVGo info
-
-#### v2.7.0
-
-> 6 May 2026
-
-- bump deps, migrate some tooling
-- feat: add AI Coding Assistant guidelines documentation
-
-#### v2.6.6
-
-> 27 April 2026
-
-- bump deps
-- feat: add nested list structure and formatting for WordPress block patterns
-- feat: add experimental formatting helpers for HTML/PHP and WordPress block patterns
-
-#### v2.6.5
-
-> 5 April 2026
-
-- fix: update setup-node action version to v6 for consistency
-
-#### v2.6.4
-
-> 5 April 2026
-
-- chore: update actions versions in npm-publish workflow and bump version-everything dependency
-- feat: add new formatting functions for handling list elements and normalize newlines
-
-#### v2.6.3
-
-> 4 April 2026
-
-- bump deps
-- feat: add formatter for WordPress block pattern PHP files and corresponding tests
-
-#### v2.6.2
-
-> 23 March 2026
-
-- feat: add error handling for WebSocket proxy requests
-
-#### v2.6.1
-
-> 23 March 2026
-
-- chore: update dependencies in package.json
-
-#### v2.6.0
-
-> 13 March 2026
-
-- bump deps, remove debug logs, resulve from sass & styles
-
-#### v2.5.1
-
-> 8 March 2026
-
-- add rimraf
-- add SVG processing details to README
-- add comment for runner images in release workflow
-
-#### v2.5.0
-
-> 7 March 2026
-
-- bump deps
-- beginning of typing, some cleanup
-- inline SVGs in SCSS files by default
-
-#### v2.4.2
-
-> 22 December 2025
-
-- Update npm publish command with options
-
-#### v2.4.1
-
-> 22 December 2025
-
-- update workflow for trusted publishing
-
-#### v2.4.0
-
-> 21 December 2025
-
-- bump deps
-- Enable loading Sass files from node_modules
-
-#### v2.3.2
-
-> 3 November 2025
-
-- bump deps
-- watch tweaks, debugging, formatting and cleanup
-
-#### v2.3.1
-
-> 21 October 2025
-
-- liveReload workaround for mini-css-extract-plugin HMR issues
-- WIP updates
-
-#### v2.3.0
-
-> 19 October 2025
-
-- Fixes and optimizations for multiple entry points
-
-#### v2.2.6
-
-> 18 October 2025
-
-- bump deps
-
-#### v2.2.5
-
-> 6 October 2025
-
-- bump deps
-- update example docker-compose file with experimental WP Multisite envvars
-
-#### v2.2.4
-
-> 10 September 2025
-
-- Make iop-format-prettier work globally
-
-#### v2.2.3
-
-> 9 September 2025
-
-- trying explicit PHP plugin loading
-
-#### v2.2.2
-
-> 9 September 2025
-
-- tweaking deps
-
-#### v2.2.1
-
-> 9 September 2025
-
-- tweak format-php-prettier, bump deps
-
-#### v2.2.0
-
-> 7 September 2025
-
-- bump deps
-- Update websocket reload for v5, cleanup
-- Testing some watch fixes
-
-#### v2.1.11
-
-> 3 September 2025
-
-- bump deps
-
-#### v2.1.10
-
-> 3 September 2025
-
-- tweak devserver hot setting
-
-#### v2.1.9
-
-> 24 August 2025
-
-- bump deps
-
-#### v2.1.8
-
-> 29 May 2025
-
-- Fix inline-whitespace wrapped php token bug
-- typo
-
-#### v2.1.7
-
-> 28 May 2025
-
-- bump deps
-- enable sourcemaps on all CSS loaders
-
-#### v2.1.6
-
-> 1 May 2025
-
-- refactor tokenizeHTML, bug fixes, tests
-- typo
-
-#### v2.1.5
-
-> 17 April 2025
-
-- escape capture group replacement strings when unTokenizing, plus tests
-- change dev site reporter emoji
-
-#### v2.1.4
-
-> 16 April 2025
-
-- use look-behind and look-forward to allow overlaps, simplify replacements
-- fix README
-
-#### v2.1.3
-
-> 16 April 2025
-
-- Use self-closing html tags as tokens. Closes #11
-
-#### v2.1.2
-
-> 14 April 2025
-
-- bump deps
-- experimental html & php formatter
-
-#### v2.1.1
-
-> 9 April 2025
-
-- Clean up outputs a little
-
-#### v2.1.0
-
-> 1 April 2025
-
-- bump deps
-- Standardize on sass-embedded, clean up, bump deps
-
-#### v2.0.6
-
-> 20 March 2025
-
-- try moving webpack-cli to peerDependencies
-
-#### v2.0.5
-
-> 20 March 2025
-
-- add note about local development to readme
-- resolve webpack loaders when running linked
-- Fix for missing content-type header
-
-#### v2.0.4
-
-> 19 March 2025
-
-- update GitHub Actions
-
-#### v2.0.3
-
-> 19 March 2025
-
-- bump deps
-- update example files
-- update devserver-proxy tests
-
-#### v2.0.2
-
-> 13 January 2025
-
-- bump deps
-
-#### v2.0.1
-
-> 19 October 2024
-
-- another Sass bump
-
-#### v2.0.0
-
-> 19 October 2024
-
-- bump deps
-- update example webpack.config file
-- bump deps
-
-#### v1.2.1
-
-> 19 September 2024
-
-- plugins updates, config fixes
-
-#### v1.2.0
-
-> 19 September 2024
-
-- deprecation free build! closes #5
-- bump deps, remove some for deprecations. Ref #5
-- bump deps, update examples and testing
-- export webpackConfig
-
-#### v1.1.14
-
-> 6 May 2024
-
-- minor bumps
-
-#### v1.1.13
-
-> 10 April 2024
-
-- bump most all the deps
-- add read-package-up, esTarget: es2020
-- readme tweak
-
-#### v1.1.12
-
-> 4 March 2024
-
-- readme badge links
-- were all these problems just a missing shebang?
-
-#### v1.1.11
-
-> 4 March 2024
-
-- Remove version from plugin builds WIP
-
-#### v1.1.10
-
-> 4 March 2024
-
-- use process.stdout references (of course)
-
-#### v1.1.9
-
-> 4 March 2024
-
-- update actions
-- missed a couple readline calls
-
-#### v1.1.8
-
-> 4 March 2024
-
-- quick remove readline function
-
-#### v1.1.7
-
-> 4 March 2024
-
-- extracting the zip script, updated deps
-- WIP example webpack.config.js file
-- update readme
-
-#### v1.1.6
-
-> 30 January 2024
-
-- test stuff and fixes
-- misc fixes and first zip testing
-
-#### v1.1.5
-
-> 25 January 2024
-
-- move the localPort stuff into devserver-proxy
-
-#### v1.1.4
-
-> 25 January 2024
-
-- deps, formatting, debugging
-
-#### v1.1.3
-
-> 24 January 2024
-
-- reconfigure imports, port-reporter to module, lots of deps
-- add changelog, update readme (badges)
-- fix path to port-reporter script
-
-#### v1.1.2
-
-> 23 January 2024
-
-#### v1.1.1
-
-> 23 January 2024
-
-- versioning, github actions, bump deps, README
-- update version in readme
-
-#### v1.1.0
-
-> 23 January 2024
-
-- add packages
-- name change, prepare for npm publish
-- add port-reporter script, giving up on linking local pacakges
-
-#### v1.0.4
-
-> 16 January 2024
-
-- embed default.config
-
-#### v1.0.3
-
-> 16 January 2024
-
-- buildConfig
-
-#### v1.0.2
-
-> 16 January 2024
-
-- add sass-embedded
-
-#### v1.0.1
-
-> 16 January 2024
-
-- add modules
-- add lib, temp exports
-- Initial commit