@imwz/wp-pattern-sentinel 1.1.5 → 1.2.1

package/README.md

@@ -4,7 +4,7 @@
 [![npm downloads](https://img.shields.io/npm/dt/@imwz/wp-pattern-sentinel.svg)](https://www.npmjs.com/package/@imwz/wp-pattern-sentinel)
 [![License](https://img.shields.io/npm/l/@imwz/wp-pattern-sentinel.svg)](https://github.com/imagewize/wp-pattern-sentinel/blob/main/package.json)
 
-Browser-based WordPress block pattern validator. Loads each pattern into the Gutenberg editor via Playwright, saves it, and checks for block validation errors and content mismatches.
+Browser-based WordPress block pattern validator. Loads each pattern into the Gutenberg editor via Playwright, saves it, and checks for block validation errors and content mismatches. Validates `.php` pattern files and `.html` files of raw block markup. See [What it validates](#what-it-validates-php-and-html).
 
 ## Why browser-based?
 
@@ -14,7 +14,7 @@ WordPress block validation is a JavaScript concern. The editor's `save()` functi
 
 Credentials are resolved in this order — the first match wins:
 
-1. **`--trellis` flag** — reads directly from Roots Trellis vault + `wordpress_sites.yml`
+1. **`--trellis` flag** — reads directly from Roots Trellis vault + `wordpress_sites.yml` (`--user` / `--pass` still override the username and password)
 2. **CLI flags** — `--url`, `--user`, `--pass`
 3. **Environment variables** — `WP_URL`, `WP_USER`, `WP_PASS`
 4. **`.env` file** — placed in the directory where you run sentinel
@@ -63,6 +63,15 @@ Sentinel auto-discovers the Trellis directory by walking up from the current wor
 
 **Bedrock support:** When `--trellis` is used, sentinel auto-detects Bedrock installs by reading `WP_SITEURL` from the site's `.env` file. Bedrock puts WordPress core in `/wp/`, so admin URLs become `/wp/wp-admin/` instead of `/wp-admin/`. No extra flags needed — this is handled automatically.
 
+**Different admin user:** Trellis provisions a WordPress user named `admin`, and that is the username Sentinel logs in with. If the local database was pulled from production, `admin` may not exist and login fails with "The username admin is not registered on this site". Pass the real admin with `--user`. Add `--pass` if that user's password differs from the vault's `admin_password`. URL and Bedrock detection still come from Trellis.
+
+```bash
+sentinel --trellis --site=example.com --user=jane path/to/patterns/
+
+# Password from your shell rather than the command line history; an empty value keeps the vault password
+sentinel --trellis --site=example.com --user=jane --pass="$WP_PASS" path/to/patterns/
+```
+
 ---
 
 ## Quickstart with `.env`
@@ -97,6 +106,9 @@ node bin/sentinel.js \
 # Validate specific files
 node bin/sentinel.js patterns/hero.php patterns/cta.php
 
+# Raw block markup (.html) — block fixtures or post drafts
+node bin/sentinel.js tests/sentinel/ drafts/my-post.html
+
 # JSON output (one result object per line)
 node bin/sentinel.js --json --url=... path/to/patterns/
 
@@ -113,13 +125,46 @@ node bin/sentinel.js --concurrency=6 --url=... path/to/patterns/
 node bin/sentinel.js --verbose --url=... path/to/patterns/
 ```
 
+## What it validates: `.php` and `.html`
+
+Sentinel never asks WordPress for registered patterns. It reads block markup from a file, puts it into a new draft page in the editor, saves the page and compares the result. So a file doesn't have to be a registered pattern; it only has to contain serialized blocks. A folder argument is scanned recursively for both extensions, skipping `node_modules`, `vendor` and dot-folders such as `.git`. Point Sentinel at the pattern or fixture folder rather than a block theme's root: `templates/*.html` and `parts/*.html` are block markup too, but they are site templates, not post content, and don't belong in a page round-trip.
+
+| Extension | What it holds | What Sentinel strips before inserting |
+|-----------|---------------|---------------------------------------|
+| `.php` | A WordPress pattern file: PHP header, then block markup | Everything up to the first `?>` (docblock, `ABSPATH` guard), then inline PHP such as `esc_html_e()` is replaced with static text |
+| `.html` | Raw serialized blocks, exactly as WordPress stores them in `post_content` | Only a **leading** header made of plain HTML comments (`<!-- SUGGESTED TITLE: … -->`) and Blade comments (`{{-- … --}}`) |
+
+### When to use `.html`
+
+- **Testing a block that no pattern uses.** A theme block that only ever appears in post content (a CTA, a callout) has no pattern file for Sentinel to pick up. Don't wrap it in a fake pattern header. Save the block's markup as it is serialized in a real post, for example copied from `wp post get <id> --field=post_content`, as `tests/sentinel/<block>.html`.
+- **Checking post or page drafts before import.** Drafts written as `.html` block markup can be validated as they are. Header notes at the top of the file are skipped. Without that, the editor would wrap them in a Classic block and Sentinel would report a false mismatch.
+
+```bash
+# A theme's block fixtures
+sentinel --trellis --site=example.com tests/sentinel/
+
+# Blog drafts before they are imported
+sentinel --trellis --site=example.com drafts/blog-posts/
+```
+
+### Rules for `.html` files
+
+- After the header, the file must start with a block comment (`<!-- wp:… -->`). Otherwise it fails with `extraction_error`.
+- Only the header is stripped. A non-block comment *after* the first block is left in, because in post content it is real content.
+- There's no PHP handling, so an `.html` file containing `<?php` is inserted as is.
+- Use markup the editor actually produced, not hand-written HTML. The test's value is that a real serialization round-trips cleanly.
+
+### Blocks with a locked template
+
+A block that renders `InnerBlocks` with a `template` and `templateLock: "all"` or `"contentOnly"` is re-synced to that template when the editor loads it. Gutenberg matches inner blocks by position, adds any the template has extra, and removes any it no longer has. A fixture holding the markup a post stored *before* a template change will therefore fail with `content_mismatch`, and that is correct. It is exactly the change an editor would see on opening such a post. Keep one fixture per current template, and run an old one on purpose when you want to see how existing posts will be affected.
+
 ## Options
 
 | Flag | Default | Description |
 |------|---------|-------------|
 | `--url` | `http://localhost` | WordPress site URL |
-| `--user` | `admin` | Admin username |
-| `--pass` | `password` | Admin password |
+| `--user` | `admin` | Admin username. Overrides the Trellis username when used with `--trellis` |
+| `--pass` | `password` | Admin password. Overrides the vault password when used with `--trellis` |
 | `--wp-subdir` | — | WP core subdir when not using `--trellis` (e.g. `wp` for Bedrock). Sets admin URL to `{url}/{subdir}`. Auto-detected from `WP_SITEURL` when `--trellis` is used. |
 | `--headless` | `true` | Run browser headless |
 | `--concurrency` | `4` | Parallel workers |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imwz/wp-pattern-sentinel",
-  "version": "1.1.5",
+  "version": "1.2.1",
   "description": "Browser-based WordPress block pattern validator using Playwright",
   "type": "module",
   "engines": {
@@ -10,7 +10,8 @@
     "sentinel": "bin/sentinel.js"
   },
   "scripts": {
-    "start": "node bin/sentinel.js"
+    "start": "node bin/sentinel.js",
+    "test": "node --test test/*.test.js"
   },
   "files": [
     "bin/",

package/src/args.js

@@ -7,6 +7,7 @@ import { findTrellisDir, loadTrellisCredentials } from './trellis.js';
 /**
  * Credential resolution priority:
  *   1. --trellis flag  → reads Roots Trellis vault + wordpress_sites.yml
+ *                        (--user / --pass still override the vault values)
  *   2. CLI flags       → --url, --user, --pass
  *   3. Env vars        → WP_URL, WP_USER, WP_PASS
  *   4. .env file       → loaded from cwd automatically
@@ -64,6 +65,19 @@ function loadDotEnv() {
   }
 }
 
+/**
+ * Let --user / --pass override credentials read from Trellis. Trellis
+ * provisions the WordPress user "admin", but a site whose database was pulled
+ * from production only has that site's real admin, so explicit flags win. An
+ * empty flag (`--pass="$UNSET_VAR"` in an npm script) keeps the vault value.
+ */
+export function applyCredentialFlags({ user, pass }, values) {
+  return {
+    user: values.user || user,
+    pass: values.pass || pass,
+  };
+}
+
 export async function parseArgs(args) {
   loadDotEnv();
 
@@ -88,6 +102,8 @@ export async function parseArgs(args) {
       subsite: values.subsite ?? null,
     }));
 
+    ({ user, pass } = applyCredentialFlags({ user, pass }, values));
+
   } else {
     // --- Source 2: CLI flags ---
     url  = values.url;
@@ -148,7 +164,7 @@ export function resolveFiles(filePaths) {
   if (!filePaths || filePaths.length === 0) {
     throw new Error(
       'No pattern files specified.\n' +
-      'Usage: sentinel [--trellis [--site=example.com]] path/to/patterns/\n' +
+      'Usage: sentinel [--trellis [--site=example.com]] path/to/patterns/  (.php and .html files)\n' +
       'Or set WP_URL, WP_USER, WP_PASS in .env'
     );
   }
@@ -162,7 +178,7 @@ export function resolveFiles(filePaths) {
     }
     const stat = fs.statSync(abs);
     if (stat.isDirectory()) {
-      resolved.push(...findPhpFiles(abs));
+      resolved.push(...findPatternFiles(abs));
     } else {
       resolved.push(abs);
     }
@@ -170,13 +186,23 @@ export function resolveFiles(filePaths) {
   return [...new Set(resolved)];
 }
 
-function findPhpFiles(dir) {
+// `.php` — WordPress pattern files. `.html` — raw serialized block markup, as
+// stored in post_content (block fixtures, post drafts).
+const PATTERN_EXTENSIONS = ['.php', '.html'];
+
+// Dependency and VCS folders are never pattern sources, but they do hold
+// stray `.php`/`.html` files (README demos, test pages) that a scan of a theme
+// root would otherwise try to validate. Dot-folders (.git, .cache) likewise.
+const SKIPPED_DIRS = new Set(['node_modules', 'vendor']);
+
+function findPatternFiles(dir) {
   const results = [];
   for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
     const full = path.join(dir, entry.name);
     if (entry.isDirectory()) {
-      results.push(...findPhpFiles(full));
-    } else if (entry.isFile() && entry.name.endsWith('.php')) {
+      if (SKIPPED_DIRS.has(entry.name) || entry.name.startsWith('.')) continue;
+      results.push(...findPatternFiles(full));
+    } else if (entry.isFile() && PATTERN_EXTENSIONS.includes(path.extname(entry.name))) {
       results.push(full);
     }
   }

package/src/editor.js

@@ -52,7 +52,9 @@ function stripPhpForValidation(content) {
  * regardless of what it contains (docblock only, or docblock + guard) — so a
  * single non-greedy strip handles both shapes in one pass.
  */
-export function extractBlockContent(fileContent) {
+export function extractBlockContent(fileContent, filePath = '') {
+  if (filePath.endsWith('.html')) return extractHtmlBlockContent(fileContent);
+
   const stripped = fileContent
     .replace(/^[\s\S]*?\?>\s*/, '')
     .trim();
@@ -61,6 +63,29 @@ export function extractBlockContent(fileContent) {
   return stripPhpForValidation(stripped);
 }
 
+/**
+ * Return the block markup of an `.html` file: serialized blocks exactly as
+ * WordPress stores them in post_content, with no PHP header.
+ *
+ * Only a *leading* header is removed — plain HTML comments that are not block
+ * delimiters (`<!-- SUGGESTED TITLE: … -->`) and Blade comments
+ * (`{{-- … --}}`). Draft files carry these as notes for humans; left in, the
+ * editor would turn them into a Classic block and report a mismatch. Comments
+ * after the first block are content and are left alone. Returns null if no
+ * block comment follows the header.
+ */
+export function extractHtmlBlockContent(fileContent) {
+  const HEADER_COMMENT = /^\s*(?:<!--(?!\s*\/?wp:)[\s\S]*?-->|\{\{--[\s\S]*?--\}\})/;
+
+  let content = fileContent;
+  while (HEADER_COMMENT.test(content)) {
+    content = content.replace(HEADER_COMMENT, '');
+  }
+  content = content.trim();
+
+  return /^<!--\s*wp:/.test(content) ? content : null;
+}
+
 const PAGE_CREATION_RETRY_DELAYS = [3_000, 8_000, 15_000]; // ms before retries 1, 2, 3 (plus jitter)
 
 /**

package/src/main.js

@@ -192,7 +192,7 @@ async function validatePatternFile(patternPath, options, context) {
     return fail(patternName, patternPath, startTime, 'file_error', error.message);
   }
 
-  const blockContent = extractBlockContent(fileContent);
+  const blockContent = extractBlockContent(fileContent, patternPath);
   if (!blockContent) {
     return fail(patternName, patternPath, startTime, 'extraction_error', 'Could not extract block content from file');
   }