@ideasonpurpose/build-tools-wordpress 2.6.6 → 2.8.0

package/.github/workflows/release-from-version-tag.yml

@@ -13,7 +13,7 @@ jobs:
 
     steps:
       # https://github.com/marketplace/actions/checkout
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Set TAG environment variable
         run: |

package/AGENTS.md

@@ -0,0 +1,68 @@
+## AI Coding Assistant Guidelines
+
+**Mantra:** Minimal. Surgical. Collaborative. Verifiable.
+
+### 0. Communicate like a senior engineer
+
+- Start with the answer, no preamble.
+- Match response length to task complexity.
+- Begin with a brief plan: what you understand, assumptions, approach.
+- Call out trade-offs explicitly (simplicity vs future-proofing, readability vs performance).
+- When ambiguous, present 2-3 concrete options with pros/cons instead of guessing.
+- Ask for confirmation on anything unclear.
+
+## 1. Think Before Coding
+
+Optimize for simplicity, maintainability, readability.
+
+**Don't assume. Don't hide confusion. Offer alternatives.**
+
+Before implementing:
+
+- State assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, offer choices — don't pick silently.
+- If a simpler approach exists, say so and push back.
+- If unclear, stop and name what's confusing.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- Delete more than you add.
+- Prefer boring, obvious code over clever code.
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- Only add error handling for realistically possible cases given current scope and style.
+- Never introduce new dependencies unless explicitly asked.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer call this overcomplicated?" If yes, simplify.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+
+- Preserve the spirit and conventions of the codebase.
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't remove comments or commented-out code.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it - don't delete it.
+
+When your changes create orphans:
+
+- Remove imports/variables/functions that _your_ changes made unused.
+- Do not remove pre-existing dead code unless asked.
+
+Every changed line should trace directly to the user's request.
+
+## 4. Documentation and Comments
+
+- Prefer self-documenting code and descriptive names over comments.
+- Add comments only where the _why_ is not obvious from the code.
+- Update or delete comments that your changes invalidate.
+- Follow the existing codebase's conventions for types, docstrings, and documentation style.
+

package/CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to this project will be documented in this file. Dates are d
 
 Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 
+#### 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

package/README.md

@@ -1,6 +1,6 @@
 # @ideasonpurpose/build-tools-wordpress
 
-#### Version 2.6.6
+#### Version 2.8.0
 
 [![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)
@@ -41,6 +41,10 @@ Webpack handles SVG files differently based on import context:
 
 Data URIs are generated as `data:image/svg+xml,<url-encoded-content>` using more efficient URL-encoding, not base64.
 
+### SVG Optimization
+
+SVGO is included along with our preferred [svgo.config.mjs][]. Run this with `npx svgo <file-to-optimize.svg>`
+
 ## Experimental formatting helpers
 
 This package includes two experimental formatting scripts:
@@ -94,6 +98,7 @@ 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" height="44" align="top" alt="IOP Logo"></a><img src="https://raw.githubusercontent.com/ideasonpurpose/ideasonpurpose/master/spacer.png" align="middle" width="4" height="54"> This project is actively developed and used in production at <a href="https://www.ideasonpurpose.com">Ideas On Purpose</a>.
+| <a href="https://www.ideasonpurpose.com"><img src="https://raw.githubusercontent.com/ideasonpurpose/ideasonpurpose/master/iop-logo-white-on-black-88px.png" height="44" align="top" alt="IOP Logo"></a> | This project is actively developed and used in production at <a href="https://www.ideasonpurpose.com">Ideas On Purpose</a>. |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
 
 <!-- END IOP CREDIT BLURB -->

package/bin/format-php-prettier.js

@@ -141,7 +141,7 @@ export function unTokenizeHTML(tokenizedHTML, phpCodeBlocks) {
  *
  * @param {string} filepath - The path to the file to format (must be a valid file path).
  */
-async function formatHTMLThenPHP(filepath) {
+export async function formatHTMLThenPHP(filepath) {
   try {
     const startTime = process.hrtime.bigint();
     const rawFile = await readFile(filepath, "utf8");
@@ -175,9 +175,11 @@ async function formatHTMLThenPHP(filepath) {
   }
 }
 
-if (process.argv[2]) {
-  const fullPath = resolve(process.argv[2]);
-  formatHTMLThenPHP(fullPath);
-} else {
-  console.error("Error: A filepath is required.");
+export async function main(filepath = process.argv[2]) {
+  if (!filepath) {
+    console.error("Error: A filepath is required.");
+    return;
+  }
+  await formatHTMLThenPHP(resolve(filepath));
 }
+if (import.meta.url === `file://${process.argv[1]}`) main();

package/bin/format-wp-block-pattern.js

@@ -108,6 +108,16 @@ export function normalizeCommentTagSpacing(content) {
       /** @param {string} match @param {string} p1 */ (match, p1) =>
         `>\n${p1}\n`,
     );
+
+    if (block === "wp:paragraph") {
+      newContent = newContent
+        .replace(/\n\s*<p>\s*/g, "\n<p>")
+        .replace(/\s*<\/p>/g, "</p>")
+        .replace(/<p>[\s\S]*?<\/p>/g, (match) =>
+          match.replace(/\s+/g, " ").trim(),
+        );
+      newContent = newContent.replace(/\n{3,}/g, "\n\n").replace(/\s+$/, "\n");
+    }
   });
   return newContent;
 }
@@ -169,38 +179,36 @@ export function formatWithPrettier(content) {
 /**
  * @param {String} filepath
  */
-async function formatWPBlockPattern(filepath) {
-  try {
-    const startTime = process.hrtime.bigint();
-    const rawFile = await readFile(filepath, "utf8");
-
-    const formatters = [
-      formatWithPrettier,
-      normalizeCommentTagSpacing,
-      formatAllWpComments,
-      trimInsideListElements,
-      trimInsideHeadings,
-      normalizeNewlines,
-    ];
-
-    const outputHtml = await formatters.reduce(
-      async (acc, fn) => fn(await acc),
-      Promise.resolve(rawFile),
-    );
+export async function formatWPBlockPattern(filepath) {
+  const startTime = process.hrtime.bigint();
+  const rawFile = await readFile(filepath, "utf8");
+
+  const formatters = [
+    formatWithPrettier,
+    normalizeCommentTagSpacing,
+    formatAllWpComments,
+    trimInsideListElements,
+    trimInsideHeadings,
+    normalizeNewlines,
+  ];
 
-    await writeFile(filepath, outputHtml, "utf8");
-    const endTime = process.hrtime.bigint();
-    const duration = Number(endTime - startTime);
+  const outputHtml = await formatters.reduce(
+    async (acc, fn) => fn(await acc),
+    Promise.resolve(rawFile),
+  );
 
-    console.log(`${basename(filepath)} ${(duration / 1e6).toFixed(2)}ms`);
-  } catch (error) {
-    console.error("Error:", error);
-  }
+  await writeFile(filepath, outputHtml, "utf8");
+  const endTime = process.hrtime.bigint();
+  const duration = Number(endTime - startTime);
+
+  console.log(`${basename(filepath)} ${(duration / 1e6).toFixed(2)}ms`);
 }
 
-if (process.argv[2]) {
-  const fullPath = resolve(process.argv[2]);
-  formatWPBlockPattern(fullPath);
-} else {
-  console.error("Error: A filepath is required.");
+export async function main(filepath = process.argv[2]) {
+  if (!filepath) {
+    console.error("Error: A filepath is required.");
+    return;
+  }
+  await formatWPBlockPattern(resolve(filepath));
 }
+if (import.meta.url === `file://${process.argv[1]}`) main();

package/boilerplate/.env.sample

@@ -0,0 +1,77 @@
+# Configuration for the Ideas On Purpose WordPress Docker environment,
+# more info here: https://github.com/ideasonpurpose/docker-wordpress-dev
+
+
+SSH_KEY_PATH=
+#   SSH_KEY_PATH should be set to the local path to your private key. For example,
+#   if you have public key named `id_ed25519_deploy.pub` associated with your managed
+#   WordPress account, SSH_KEY_PATH should point to the pair's matching private
+#   key like this:  SSH_KEY_PATH="~/.ssh/id_ed25519_deploy"
+
+
+SSH_LOGIN=
+#   SSH_LOGIN should be set to the SSH Login string from WP Engine's or Kinsta's
+#   admin backend. They should look something like this:
+#   - wpengine:   "iop001@iop001.ssh.wpengine.net"
+#   - kinsta:     "ssh iop001@11.22.33.44 -p 54321"
+#   In the above examples the elements map like this:
+#        `${SSH_USER}@${SSH_HOST}`
+#   Each item can also be entered individually, and individual entries will take
+#   precedence over components extracted from SSH_LOGIN.
+#   Values should be quoted for compatibility with Docker Compose v2.x
+
+
+SSH_USER=
+#   The user account which connects to the server. For WP Engine, this matches the
+#   environment name.
+
+
+SSH_HOST=
+#   The server address to connect to.
+
+
+SSH_PORT=
+#   The server port listening for SSH connections
+
+
+SSH_WP_CONTENT_DIR=
+#   default:  sites/${SSH_USER}/wp-content
+#   SSH_WP_CONTENT_DIR is the path to the wordpress wp-content directory. This will
+#   most likely match the `WP_CONTENT_DIR` WordPress constant and does not include
+#   a trailing slash.
+#   Path can be relative to the SSH user home folder or an absolute path.
+#   Examples:
+#    - wpengine:  sites/${SSH_USER}/wp-content
+#    - kinsta:    public/wp-content
+
+
+IOP_DEV_PLUGIN_1=
+IOP_DEV_PLUGIN_2=
+IOP_DEV_PLUGIN_3=
+IOP_DEV_PLUGIN_4=
+IOP_DEV_PLUGIN_5=
+IOP_DEV_PLUGIN_6=
+IOP_DEV_PLUGIN_7=
+IOP_DEV_PLUGIN_8=
+#   Additional development plugins can be mounted into the WordPress environment as
+#   individual volumes. The local relative path to the working plugin directory should
+#   be pointed to the absolute path inside the container. In the following example,
+#   an example-plugin project is being developed in a sibling directory to the theme:
+#
+#     IOP_DEV_PLUGIN_1="../example-plugin:/var/www/html/wp-content/plugins/example-plugin"
+
+
+WORDPRESS_DEBUG=1
+#   This is used to set the WP_DEBUG constant to toggle WordPress debugging.
+#   .env vars are imported as strings, so true/false will not work correctly.
+#   PHP does correctly coerce the integers 0 and 1 to their corresponding boolean values.
+#   PHP interprets the number 0 as a string to boolean false
+#   Leave this value blank or set it to 0 to disable WP_DEBUG
+#   Setting this to 1, true or any other non-empty string enables WP_DEBUG
+
+
+WP_ENVIRONMENT_TYPE=
+#   Blank or one of 'production', 'staging' or 'development'. For IOP's development
+#   environments, this value defaults to 'development'. Otherwise WordPress defaults
+#   to 'production'. Documentation:
+#   https://developer.wordpress.org/reference/functions/wp_get_environment_type/

package/boilerplate/composer.json

@@ -0,0 +1,42 @@
+{
+  "name": "ideasonpurpose/iop-theme",
+  "description": "Block-based hybrid theme for the Stone Rabbit NYC website.",
+  "authors": [
+    {
+      "name": "Ideas On Purpose",
+      "homepage": "https://www.ideasonpurpose.com"
+    }
+  ],
+  "config": {
+    "optimize-autoloader": true,
+    "sort-packages": true,
+    "vendor-dir": "wp-content/themes/iop-theme/vendor",
+    "platform": {
+      "php": "8.4",
+      "ext-intl": "0"
+    }
+  },
+  "autoload": {
+    "psr-4": {
+      "IdeasOnPurpose\\": [
+        "wp-content/themes/iop-theme/lib"
+      ]
+    }
+  },
+  "require": {
+    "ideasonpurpose/wp-admin-separators": "1.0.8",
+    "ideasonpurpose/wp-google-analytics": "^1.1.0",
+    "ideasonpurpose/wp-svg-lib": "^3.2.0",
+    "ideasonpurpose/wp-theme-i18n": "dev-main",
+    "ideasonpurpose/wp-theme-init": "^2.20.5"
+  },
+  "repositories": [
+    {
+      "type": "vcs",
+      "url": "https://github.com/ideasonpurpose/wp-theme-i18n"
+    }
+  ],
+  "require-dev": {
+    "php-stubs/acf-pro-stubs": "^6.5"
+  }
+}

package/boilerplate/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "iop-theme",
+  "version": "0.1.10",
+  "private": true,
+  "description": "Theme for the CLIENT_NAME website",
+  "license": "UNLICENSED",
+  "author": "Ideas On Purpose (https://www.ideasonpurpose.com/)",
+  "contributors": [
+    "Joe Maller <joe@ideasonpurpose.com>",
+    "Codrin Pavel <codrin@ideasonpurpose.com>"
+  ],
+  "type": "module",
+  "main": "index.js",
+  "scripts": {
+    "_bootstrap:composer": "npm run composer:install",
+    "_bootstrap:npm": "npm ci",
+    "prebootstrap": "npm run permissions:repair",
+    "bootstrap": "npm run _bootstrap:npm && npm run _bootstrap:composer && npm run theme:activate",
+    "postbootstrap": "echo && echo '  🚀' && echo '     ✨ All set!' && echo '🌏      Run this to get started:' && chalk bold yellow  '        npm run start' && echo",
+    "prebuild": "npm run clean",
+    "build": "NODE_ENV=production webpack",
+    "postbuild": "npm run zip",
+    "clean": "npx rimraf -g 'wp-content/themes/iop*/dist'",
+    "composer": "npm run composer:install",
+    "composer:install": "docker compose run --rm composer",
+    "composer:require": "docker compose run --rm composer require",
+    "composer:update": "docker compose run --rm composer update",
+    "db:admin": "docker compose run --rm --service-ports phpmyadmin",
+    "db:dump": "docker compose run --rm db-dump",
+    "db:pull": "npm run pull:db",
+    "db:reload": "docker compose run --rm db-reload",
+    "postdb:reload": "npm run theme:activate",
+    "dev": "npm run start",
+    "log:wordpress": "npm run logs:wordpress",
+    "logs:wordpress": "docker compose exec wordpress tail -f /var/log/wordpress/debug.log",
+    "mysqldump": "npm run db:dump",
+    "permissions:repair": "docker compose run --rm repair-permissions",
+    "phpmyadmin": "npm run db:admin",
+    "preproject:refresh": "docker compose pull refresh",
+    "project:refresh": "docker compose run --rm refresh",
+    "postproject:refresh": "docker compose pull wordpress",
+    "pull": "npm run pull:db && npm run pull:plugins && npm run pull:uploads",
+    "prepull:db": "npm run db:dump",
+    "pull:db": "docker compose run --rm pull database",
+    "postpull:db": "npm run db:reload",
+    "pull:plugins": "docker compose run --rm pull plugins",
+    "pull:uploads": "docker compose run --rm pull uploads",
+    "pull:uploads-all": "docker compose run --rm pull uploads all",
+    "prestart": "npm run clean && docker compose run --rm --service-ports -d wordpress && iop-build-port-reporter",
+    "start": "webpack serve",
+    "poststart": "npm run stop",
+    "stop": "docker compose down --remove-orphans",
+    "test": "playwright test --ui",
+    "theme:activate": "docker compose run --rm theme-activate",
+    "version": "version-everything && git add -u",
+    "postversion": "npm run build",
+    "webgrind": "docker compose run --rm --service-ports webgrind",
+    "wp-cli": "docker compose exec -u wp wordpress",
+    "zip": "iop-build-zip-archive"
+  },
+  "prettier": "@ideasonpurpose/prettier-config",
+  "stylelint": {
+    "extends": "@ideasonpurpose/stylelint-config"
+  },
+  "devDependencies": {
+    "@ideasonpurpose/build-tools-wordpress": "^2.5.1"
+  },
+  "version-everything": {
+    "files": [
+      "README.md",
+      "wp-content/themes/iop-theme/style.css"
+    ]
+  }
+}

package/boilerplate/svgo.config.mjs

@@ -0,0 +1,32 @@
+/**
+ * This is primarily intended to work with the SVGO VS Code Plugin, and to
+ * save trips out to SVGOMG.
+ *
+ * This config allows for immediate optimization of SVGs in the editor
+ *
+ *
+ * @links
+ * - SVGO: https://github.com/svg/svgo
+ * - SVGO preset-default docs: https://svgo.dev/docs/preset-default
+ * - VS Code Plugin: https://marketplace.visualstudio.com/items?itemName=1000ch.svgo
+ * - SVGOMG: https://jakearchibald.github.io/svgomg/
+ */
+
+export default {
+  js2svg: {
+    indent: 4, // number
+    pretty: true, // boolean
+  },
+
+  plugins: [
+    {
+      name: "preset-default",
+      params: {
+        overrides: {
+          cleanupIds: false,
+        },
+      },
+    },
+    "removeDimensions",
+  ],
+};