@imwz/wp-pattern-sentinel 0.1.0

package/README.md

@@ -0,0 +1,154 @@
+# wp-pattern-sentinel
+
+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.
+
+## Why browser-based?
+
+WordPress block validation is a JavaScript concern. The editor's `save()` function can inject styles, reorder CSS classes, and drop attributes in ways that PHP cannot replicate. Only a real browser can catch these errors.
+
+## Credentials
+
+Credentials are resolved in this order — the first match wins:
+
+1. **`--trellis` flag** — reads directly from Roots Trellis vault + `wordpress_sites.yml`
+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
+5. **Interactive prompt** — sentinel asks if nothing else is set (password is masked)
+
+`.env` is git-ignored. Never commit real credentials.
+
+---
+
+## Roots Trellis integration
+
+If your project uses [Roots Trellis](https://roots.io/trellis/), pass `--trellis` and sentinel reads everything it needs from the vault and `wordpress_sites.yml` — no manual credential setup required.
+
+```bash
+# Auto-detect site from cwd, use development env
+sentinel --trellis path/to/patterns/
+
+# Specify a site explicitly
+sentinel --trellis --site=demo.imagewize.com path/to/patterns/
+
+# Validate a multisite subsite
+sentinel --trellis --site=demo.imagewize.com --subsite=store path/to/patterns/
+
+# Staging or production vault
+sentinel --trellis --env=staging --site=imagewize.com path/to/patterns/
+
+# Explicit trellis directory (if auto-discovery fails)
+sentinel --trellis --trellis-dir=/path/to/trellis path/to/patterns/
+```
+
+**Requirements:**
+- `ansible-vault` installed (`brew install ansible` or `pip install ansible`)
+- `trellis/.vault_pass` present (standard Trellis setup)
+
+Sentinel auto-discovers the Trellis directory by walking up from the current working directory. It also auto-detects the site by matching cwd against each site's `local_path` in `wordpress_sites.yml`.
+
+**Trellis flags:**
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--trellis` | — | Enable Trellis credential source |
+| `--trellis-dir` | auto-discover | Path to your `trellis/` directory |
+| `--site` | auto-detect from cwd | Site key, e.g. `demo.imagewize.com` |
+| `--env` | `development` | Trellis environment (`development`, `staging`, `production`) |
+| `--subsite` | — | Multisite subsite slug (appended to URL) |
+
+---
+
+## Quickstart with `.env`
+
+```bash
+cp .env.example .env
+# edit .env with your site URL and admin credentials
+```
+
+---
+
+## Install
+
+```bash
+npm install
+npx playwright install chromium
+```
+
+## Usage
+
+```bash
+# Minimal — credentials come from .env
+node bin/sentinel.js path/to/patterns/
+
+# Validate a directory (credentials via flags)
+node bin/sentinel.js \
+  --url=http://imagewize.test \
+  --user=admin \
+  --pass=secret \
+  path/to/patterns/
+
+# Validate specific files
+node bin/sentinel.js patterns/hero.php patterns/cta.php
+
+# JSON output (one result object per line)
+node bin/sentinel.js --json --url=... path/to/patterns/
+
+# Keep draft pages in WordPress after validation
+node bin/sentinel.js --keep-page --url=... path/to/patterns/
+
+# Run headed (watch the browser)
+node bin/sentinel.js --no-headless --url=... path/to/patterns/
+
+# Adjust concurrency (default: 4)
+node bin/sentinel.js --concurrency=6 --url=... path/to/patterns/
+```
+
+## Options
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--url` | `http://localhost` | WordPress site URL |
+| `--user` | `admin` | Admin username |
+| `--pass` | `password` | Admin password |
+| `--headless` | `true` | Run browser headless |
+| `--concurrency` | `4` | Parallel workers |
+| `--json` | `false` | Output JSON (one result per line) |
+| `--keep-page` | `false` | Don't delete draft pages after validation |
+| `--width` | `1280` | Viewport width |
+| `--height` | `800` | Viewport height |
+
+## Architecture
+
+```
+bin/sentinel.js      CLI entry point
+src/
+  main.js            Orchestration — context pool, p-queue, summary
+  login.js           loginToWordPress()
+  editor.js          createDraftPage, insertPatternIntoEditor, savePage, deletePage, extractBlockContent
+  validation.js      checkBlockValidation, compareContent
+  args.js            parseArgs, resolveFiles
+  format.js          log, formatResult, printSummary
+```
+
+Each worker gets its own authenticated `BrowserContext` so session failures are isolated. Login happens once per context before the queue starts.
+
+## npm publish
+
+When ready to publish:
+
+```bash
+npm login
+npm publish --access public
+```
+
+Then use globally:
+
+```bash
+npx wp-pattern-sentinel --url=http://imagewize.test --user=admin --pass=secret patterns/
+```
+
+## Exit codes
+
+- `0` — all patterns passed
+- `1` — one or more patterns failed

package/bin/sentinel.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main } from '../src/main.js';
+
+main().catch(err => {
+  console.error(err.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@imwz/wp-pattern-sentinel",
+  "version": "0.1.0",
+  "description": "Browser-based WordPress block pattern validator using Playwright",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "sentinel": "bin/sentinel.js"
+  },
+  "scripts": {
+    "start": "node bin/sentinel.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md"
+  ],
+  "keywords": [
+    "wordpress",
+    "gutenberg",
+    "block-patterns",
+    "playwright",
+    "validation"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "js-yaml": "^4.1.0",
+    "p-queue": "^8.0.1",
+    "playwright": "^1.44.0"
+  },
+  "contributors": [
+    {
+      "name": "Jasper Frumau",
+      "email": "jasper@imagewize.com"
+    }
+  ]
+}

package/src/args.js

@@ -0,0 +1,162 @@
+import { parseArgs as nodeParseArgs } from 'util';
+import path from 'path';
+import fs from 'fs';
+import { prompt } from './prompt.js';
+import { findTrellisDir, loadTrellisCredentials } from './trellis.js';
+
+/**
+ * Credential resolution priority:
+ *   1. --trellis flag  → reads Roots Trellis vault + wordpress_sites.yml
+ *   2. CLI flags       → --url, --user, --pass
+ *   3. Env vars        → WP_URL, WP_USER, WP_PASS
+ *   4. .env file       → loaded from cwd automatically
+ *   5. Interactive     → prompted if still missing (password is masked)
+ */
+
+const ARG_OPTIONS = {
+  // Credentials
+  url:           { type: 'string' },
+  user:          { type: 'string' },
+  pass:          { type: 'string' },
+  // Trellis integration
+  trellis:       { type: 'boolean', default: false },
+  'trellis-dir': { type: 'string' },
+  site:          { type: 'string' },
+  env:           { type: 'string',  default: 'development' },
+  subsite:       { type: 'string' },
+  // Behaviour
+  headless:      { type: 'boolean', default: true },
+  json:          { type: 'boolean', default: false },
+  'keep-page':   { type: 'boolean', default: false },
+  concurrency:   { type: 'string',  default: '4' },
+  width:         { type: 'string',  default: '1280' },
+  height:        { type: 'string',  default: '800' },
+};
+
+/**
+ * Parse a .env file and add any keys not already in process.env.
+ * Supports KEY=value, KEY="value", KEY='value', and # comments.
+ * Silently skips if no .env file exists.
+ */
+function loadDotEnv() {
+  const envPath = path.join(process.cwd(), '.env');
+  try {
+    const content = fs.readFileSync(envPath, 'utf8');
+    for (const line of content.split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith('#')) continue;
+      const eq = trimmed.indexOf('=');
+      if (eq === -1) continue;
+      const key = trimmed.slice(0, eq).trim();
+      const val = trimmed.slice(eq + 1).trim().replace(/^["']|["']$/g, '');
+      if (!(key in process.env)) process.env[key] = val;
+    }
+  } catch {
+    // No .env — that's fine
+  }
+}
+
+export async function parseArgs(args) {
+  loadDotEnv();
+
+  const { values, positionals } = nodeParseArgs({
+    args,
+    options: ARG_OPTIONS,
+    allowPositionals: true,
+  });
+
+  let url, user, pass;
+
+  // --- Source 1: Trellis vault ---
+  if (values.trellis) {
+    const trellisDir = values['trellis-dir']
+      ? path.resolve(values['trellis-dir'])
+      : findTrellisDir();
+
+    ({ url, user, pass } = loadTrellisCredentials({
+      trellisDir,
+      site:    values.site,
+      env:     values.env,
+      subsite: values.subsite ?? null,
+    }));
+
+  } else {
+    // --- Source 2: CLI flags ---
+    url  = values.url;
+    user = values.user;
+    pass = values.pass;
+
+    // --- Source 3+4: Env vars / .env file ---
+    url  ??= process.env.WP_URL;
+    user ??= process.env.WP_USER;
+    pass ??= process.env.WP_PASS;
+
+    // --- Source 5: Interactive prompt ---
+    if (!url) {
+      url = await prompt('WordPress URL (e.g. http://site.test): ');
+      if (!url) throw new Error('WordPress URL is required.');
+    }
+    if (!user) {
+      user = await prompt('WordPress admin username: ');
+      if (!user) throw new Error('WordPress username is required.');
+    }
+    if (!pass) {
+      pass = await prompt('WordPress admin password: ', { hidden: true });
+      if (!pass) throw new Error('WordPress password is required.');
+    }
+  }
+
+  return {
+    url:         url.replace(/\/$/, ''),
+    user,
+    pass,
+    headless:    values.headless,
+    json:        values.json,
+    keepPage:    values['keep-page'],
+    concurrency: Math.max(1, parseInt(values.concurrency, 10)),
+    viewport: {
+      width:  parseInt(values.width,  10),
+      height: parseInt(values.height, 10),
+    },
+    files: positionals,
+  };
+}
+
+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' +
+      'Or set WP_URL, WP_USER, WP_PASS in .env'
+    );
+  }
+
+  const resolved = [];
+  for (const filePath of filePaths) {
+    const abs = path.resolve(filePath);
+    if (!fs.existsSync(abs)) {
+      console.warn(`Warning: path not found — ${filePath}`);
+      continue;
+    }
+    const stat = fs.statSync(abs);
+    if (stat.isDirectory()) {
+      resolved.push(...findPhpFiles(abs));
+    } else {
+      resolved.push(abs);
+    }
+  }
+  return [...new Set(resolved)];
+}
+
+function findPhpFiles(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')) {
+      results.push(full);
+    }
+  }
+  return results;
+}

package/src/editor.js

@@ -0,0 +1,123 @@
+import { log } from './format.js';
+
+/**
+ * Strip the PHP file header (opening tag + docblock) and return the raw block markup.
+ * Returns null if no block comment is found.
+ *
+ * WordPress pattern files look like:
+ *   <?php
+ *   /**
+ *    * Title: My Pattern
+ *    * ...
+ *    *\/
+ *   ?>
+ *   <!-- wp:group -->...
+ */
+export function extractBlockContent(fileContent) {
+  const stripped = fileContent
+    .replace(/^<\?php\s*/m, '')
+    .replace(/\/\*\*[\s\S]*?\*\//m, '')
+    .replace(/^\s*\?>\s*/m, '')
+    .trim();
+
+  if (!stripped.startsWith('<!--')) return null;
+  return stripped;
+}
+
+/**
+ * Navigate to a new draft page and return its post ID.
+ * WordPress redirects post-new.php → post.php?post=ID&action=edit,
+ * so we can read the ID directly from the final URL.
+ */
+export async function createDraftPage(page, baseUrl) {
+  try {
+    await page.goto(`${baseUrl}/wp-admin/post-new.php?post_type=page`, {
+      waitUntil: 'domcontentloaded',
+      timeout: 30000,
+    });
+
+    await page.waitForSelector('.edit-post-layout, .editor-styles-wrapper', {
+      timeout: 30000,
+    });
+
+    const url = page.url();
+    const match = url.match(/[?&]post=(\d+)/);
+    if (match) return parseInt(match[1], 10);
+
+    // Fallback: read from wp.data (editor may not have redirected yet)
+    return await page.evaluate(() =>
+      window.wp?.data?.select('core/editor')?.getCurrentPostId?.() ?? null
+    );
+  } catch (error) {
+    log(`Failed to create draft page: ${error.message}`, 'red');
+    return null;
+  }
+}
+
+/**
+ * Set the editor content via wp.data and wait for blocks to parse.
+ */
+export async function insertPatternIntoEditor(page, blockContent) {
+  try {
+    await page.evaluate(content => {
+      window.wp.data.dispatch('core/editor').editPost({ content });
+    }, blockContent);
+
+    // Wait until at least one block is present
+    await page.waitForFunction(
+      () => window.wp.data.select('core/block-editor').getBlocks().length > 0,
+      { timeout: 15000 }
+    );
+
+    return true;
+  } catch (error) {
+    log(`Failed to insert pattern: ${error.message}`, 'red');
+    return false;
+  }
+}
+
+/**
+ * Trigger savePost() and wait for the editor to finish saving.
+ */
+export async function savePage(page) {
+  const result = { success: false, errors: [], warnings: [] };
+  try {
+    await page.evaluate(() => window.wp.data.dispatch('core/editor').savePost());
+
+    // Wait for save to start, then finish
+    await page
+      .waitForFunction(
+        () => window.wp.data.select('core/editor').isSavingPost(),
+        { timeout: 5000 }
+      )
+      .catch(() => {}); // save might be near-instant
+
+    await page.waitForFunction(
+      () => !window.wp.data.select('core/editor').isSavingPost(),
+      { timeout: 30000 }
+    );
+
+    result.success = true;
+  } catch (error) {
+    result.errors.push({ type: 'save_error', message: error.message });
+  }
+  return result;
+}
+
+/**
+ * Delete the draft page via the WP REST API (uses the active browser session's nonce).
+ * Non-fatal — a failure here does not affect validation results.
+ */
+export async function deletePage(page, baseUrl, pageId) {
+  try {
+    await page.evaluate(async id => {
+      const nonce = window.wpApiSettings?.nonce ?? '';
+      await fetch(`/wp-json/wp/v2/pages/${id}?force=true`, {
+        method: 'DELETE',
+        headers: { 'X-WP-Nonce': nonce },
+      });
+    }, pageId);
+  } catch {
+    // Non-fatal
+  }
+}

package/src/format.js

@@ -0,0 +1,49 @@
+const C = {
+  reset:  '\x1b[0m',
+  red:    '\x1b[31m',
+  green:  '\x1b[32m',
+  yellow: '\x1b[33m',
+  cyan:   '\x1b[36m',
+  gray:   '\x1b[90m',
+};
+
+export function log(message, color = 'reset') {
+  console.log(`${C[color] ?? C.reset}${message}${C.reset}`);
+}
+
+export function formatResult(result) {
+  const status = result.passed
+    ? `${C.green}✓ PASS${C.reset}`
+    : `${C.red}✗ FAIL${C.reset}`;
+
+  const lines = [`${status}  ${result.pattern}  (${result.duration}ms)`];
+
+  for (const err of result.errors) {
+    lines.push(`       ${C.red}ERROR${C.reset} [${err.type}] ${err.message}`);
+  }
+  for (const warn of result.warnings) {
+    lines.push(`       ${C.yellow}WARN${C.reset}  [${warn.type}] ${warn.message}`);
+  }
+
+  return lines.join('\n');
+}
+
+export function printSummary(results) {
+  const passed       = results.filter(r => r.passed).length;
+  const failed       = results.filter(r => !r.passed).length;
+  const totalErrors  = results.reduce((n, r) => n + r.errors.length, 0);
+  const totalWarns   = results.reduce((n, r) => n + r.warnings.length, 0);
+  const totalMs      = results.reduce((n, r) => n + r.duration, 0);
+  const avgMs        = Math.round(totalMs / results.length);
+
+  log('\n' + '='.repeat(60));
+  log('Validation Summary', 'cyan');
+  log('='.repeat(60));
+  log(`Patterns  : ${results.length}`);
+  log(`Passed    : ${passed}`,       passed      > 0 ? 'green'  : 'gray');
+  log(`Failed    : ${failed}`,       failed      > 0 ? 'red'    : 'gray');
+  log(`Errors    : ${totalErrors}`,  totalErrors > 0 ? 'red'    : 'gray');
+  log(`Warnings  : ${totalWarns}`,   totalWarns  > 0 ? 'yellow' : 'gray');
+  log(`Time      : ${totalMs}ms  (avg ${avgMs}ms/pattern)`);
+  console.log('');
+}

package/src/login.js

@@ -0,0 +1,18 @@
+import { log } from './format.js';
+
+export async function loginToWordPress(page, url, user, pass) {
+  try {
+    await page.goto(`${url}/wp-login.php`, {
+      waitUntil: 'domcontentloaded',
+      timeout: 30000,
+    });
+    await page.fill('#user_login', user);
+    await page.fill('#user_pass', pass);
+    await page.click('#wp-submit');
+    await page.waitForURL(`${url}/wp-admin/**`, { timeout: 15000 });
+    return true;
+  } catch (error) {
+    log(`Login failed: ${error.message}`, 'red');
+    return false;
+  }
+}

package/src/main.js

@@ -0,0 +1,150 @@
+import { chromium } from 'playwright';
+import PQueue from 'p-queue';
+import path from 'path';
+import fs from 'fs';
+import { parseArgs, resolveFiles } from './args.js';
+import { loginToWordPress } from './login.js';
+import {
+  extractBlockContent,
+  createDraftPage,
+  insertPatternIntoEditor,
+  savePage,
+  deletePage,
+} from './editor.js';
+import { checkBlockValidation, compareContent } from './validation.js';
+import { log, formatResult, printSummary } from './format.js';
+
+export async function main() {
+  const options = await parseArgs(process.argv.slice(2));
+  const files   = resolveFiles(options.files);
+
+  if (files.length === 0) {
+    log('No pattern files found.', 'red');
+    process.exit(1);
+  }
+
+  log(`\nFound ${files.length} pattern(s) — concurrency: ${options.concurrency}`, 'cyan');
+
+  const browser = await chromium.launch({
+    headless: options.headless,
+    args: ['--disable-web-security'],
+  });
+
+  // One authenticated context per worker — sessions are fully isolated
+  let contexts;
+  try {
+    contexts = await Promise.all(
+      Array.from({ length: options.concurrency }, async () => {
+        const context = await browser.newContext({ viewport: options.viewport });
+        const page    = await context.newPage();
+        page.setDefaultTimeout(60000);
+        const ok = await loginToWordPress(page, options.url, options.user, options.pass);
+        await page.close();
+        if (!ok) throw new Error('Failed to authenticate with WordPress');
+        return context;
+      })
+    );
+  } catch (error) {
+    log(error.message, 'red');
+    await browser.close();
+    process.exit(1);
+  }
+
+  const queue = new PQueue({ concurrency: options.concurrency });
+  let idx = 0;
+
+  // Push ALL tasks without awaiting — this is what makes workers run in parallel
+  const promises = files.map(file => {
+    const context = contexts[idx++ % options.concurrency];
+    return queue.add(() => validatePatternFile(file, options, context));
+  });
+
+  const results = await Promise.all(promises);
+
+  await Promise.all(contexts.map(c => c.close()));
+  await browser.close();
+
+  if (options.json) {
+    for (const r of results) console.log(JSON.stringify(r));
+  } else {
+    for (const r of results) console.log(formatResult(r));
+    printSummary(results);
+  }
+
+  process.exit(results.some(r => !r.passed) ? 1 : 0);
+}
+
+async function validatePatternFile(patternPath, options, context) {
+  const patternName = path.basename(patternPath);
+  const startTime   = Date.now();
+
+  let fileContent;
+  try {
+    fileContent = await fs.promises.readFile(patternPath, 'utf8');
+  } catch (error) {
+    return fail(patternName, startTime, 'file_error', error.message);
+  }
+
+  const blockContent = extractBlockContent(fileContent);
+  if (!blockContent) {
+    return fail(patternName, startTime, 'extraction_error', 'Could not extract block content from file');
+  }
+
+  const page = await context.newPage();
+  page.setDefaultTimeout(60000);
+
+  try {
+    const pageId = await createDraftPage(page, options.url);
+    if (pageId === null) {
+      return fail(patternName, startTime, 'page_creation_error', 'Failed to create test page');
+    }
+
+    if (!(await insertPatternIntoEditor(page, blockContent))) {
+      await deletePage(page, options.url, pageId);
+      return fail(patternName, startTime, 'insertion_error', 'Failed to insert pattern into editor');
+    }
+
+    const saveResult  = await savePage(page);
+    const blockErrors = await checkBlockValidation(page);
+
+    if (blockErrors.length > 0) {
+      saveResult.errors.push(...blockErrors.map(e => ({
+        type:    'block_validation',
+        message: `${e.blockName} (${e.blockId}): ${e.error}`,
+      })));
+    }
+
+    const comparison = await compareContent(page, blockContent);
+    saveResult.errors.push(...comparison.errors);
+    saveResult.warnings.push(...comparison.warnings);
+
+    if (!options.keepPage) {
+      await deletePage(page, options.url, pageId);
+    }
+
+    return {
+      pattern:      patternName,
+      passed:       saveResult.success && comparison.matches && blockErrors.length === 0,
+      errors:       saveResult.errors,
+      warnings:     saveResult.warnings,
+      duration:     Date.now() - startTime,
+      savedContent: comparison.savedContent,
+    };
+
+  } catch (error) {
+    log(`Unexpected error — ${patternName}: ${error.message}`, 'red');
+    return fail(patternName, startTime, 'validation_error', error.message);
+  } finally {
+    await page.close();
+  }
+}
+
+function fail(pattern, startTime, type, message) {
+  return {
+    pattern,
+    passed:   false,
+    errors:   [{ type, message }],
+    warnings: [],
+    duration: Date.now() - startTime,
+  };
+}

package/src/prompt.js

@@ -0,0 +1,44 @@
+import { createInterface } from 'readline';
+
+/**
+ * Prompt the user for a value. Pass hidden: true for passwords
+ * (masks input with asterisks).
+ */
+export function prompt(question, { hidden = false } = {}) {
+  return new Promise(resolve => {
+    if (!hidden) {
+      const rl = createInterface({ input: process.stdin, output: process.stdout });
+      rl.question(question, answer => { rl.close(); resolve(answer); });
+      return;
+    }
+
+    process.stdout.write(question);
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding('utf8');
+
+    let value = '';
+
+    const onData = char => {
+      if (char === '\r' || char === '\n' || char === '') {
+        process.stdin.setRawMode(false);
+        process.stdin.pause();
+        process.stdin.removeListener('data', onData);
+        process.stdout.write('\n');
+        resolve(value);
+      } else if (char === '' || char === '') {
+        if (value.length > 0) {
+          value = value.slice(0, -1);
+          process.stdout.clearLine(0);
+          process.stdout.cursorTo(0);
+          process.stdout.write(question + '*'.repeat(value.length));
+        }
+      } else {
+        value += char;
+        process.stdout.write('*');
+      }
+    };
+
+    process.stdin.on('data', onData);
+  });
+}

package/src/trellis.js

@@ -0,0 +1,113 @@
+import { execSync } from 'child_process';
+import path from 'path';
+import fs from 'fs';
+import yaml from 'js-yaml';
+
+/**
+ * Walk up from startDir looking for a directory that contains group_vars/
+ * (the Trellis signature). Checks both the dir itself and a trellis/ subdir.
+ */
+export function findTrellisDir(startDir = process.cwd()) {
+  let dir = path.resolve(startDir);
+
+  for (let i = 0; i < 10; i++) {
+    // Direct match (we're already inside the trellis dir)
+    if (fs.existsSync(path.join(dir, 'group_vars'))) return dir;
+
+    // Sibling trellis/ directory
+    const sibling = path.join(dir, 'trellis');
+    if (fs.existsSync(path.join(sibling, 'group_vars'))) return sibling;
+
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  throw new Error(
+    'Could not find Trellis directory (looking for group_vars/ marker).\n' +
+    'Run sentinel from inside your project, or pass --trellis-dir=/path/to/trellis.'
+  );
+}
+
+/**
+ * Try to match the current working directory against a site's local_path
+ * to auto-select which site to validate. Returns the site key or null.
+ *
+ * local_path in wordpress_sites.yml is relative to the trellis directory.
+ */
+function detectSiteFromCwd(trellisDir, sites) {
+  const cwd = process.cwd();
+  for (const [key, config] of Object.entries(sites)) {
+    if (!config.local_path) continue;
+    const abs = path.resolve(trellisDir, config.local_path);
+    if (cwd.startsWith(abs)) return key;
+  }
+  return null;
+}
+
+/**
+ * Load credentials from Trellis vault and wordpress_sites.yml.
+ *
+ * Options:
+ *   trellisDir  — absolute path to the trellis directory
+ *   site        — site key, e.g. "demo.imagewize.com" (auto-detected if omitted)
+ *   env         — "development" | "staging" | "production" (default: "development")
+ *   subsite     — multisite subsite slug appended to the URL (e.g. "store")
+ *
+ * Returns { url, user, pass }
+ */
+export function loadTrellisCredentials({ trellisDir, site, env = 'development', subsite = null }) {
+  const vaultFile     = path.join(trellisDir, 'group_vars', env, 'vault.yml');
+  const vaultPassFile = path.join(trellisDir, '.vault_pass');
+  const sitesFile     = path.join(trellisDir, 'group_vars', env, 'wordpress_sites.yml');
+
+  for (const [label, p] of [['Vault password file', vaultPassFile], ['Sites file', sitesFile]]) {
+    if (!fs.existsSync(p)) throw new Error(`${label} not found: ${p}`);
+  }
+
+  // Decrypt vault with ansible-vault
+  let vaultContent;
+  try {
+    vaultContent = execSync(
+      `ansible-vault view --vault-password-file "${vaultPassFile}" "${vaultFile}"`,
+      { cwd: trellisDir, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
+    );
+  } catch (err) {
+    throw new Error(`Failed to decrypt Trellis vault: ${err.message}`);
+  }
+
+  const vault = yaml.load(vaultContent);
+  const sites = yaml.load(fs.readFileSync(sitesFile, 'utf8'));
+
+  const vaultSites = vault.vault_wordpress_sites ?? {};
+  const wordpressSites = sites.wordpress_sites ?? {};
+
+  // Auto-detect site from cwd, then fall back to first site in the file
+  const siteKey = site
+    ?? detectSiteFromCwd(trellisDir, wordpressSites)
+    ?? Object.keys(wordpressSites)[0];
+
+  if (!vaultSites[siteKey]) {
+    const available = Object.keys(vaultSites).join(', ');
+    throw new Error(`Site "${siteKey}" not found in vault. Available: ${available}`);
+  }
+  if (!wordpressSites[siteKey]) {
+    throw new Error(`Site "${siteKey}" not found in wordpress_sites.yml`);
+  }
+
+  const adminPassword = vaultSites[siteKey].admin_password;
+  if (!adminPassword) {
+    throw new Error(`No admin_password for "${siteKey}" in vault`);
+  }
+
+  // Build URL from canonical hostname + SSL setting
+  const canonical = wordpressSites[siteKey].site_hosts[0].canonical;
+  const ssl        = wordpressSites[siteKey].ssl?.enabled ?? false;
+  const protocol   = ssl ? 'https' : 'http';
+  const url        = subsite
+    ? `${protocol}://${canonical}/${subsite}`
+    : `${protocol}://${canonical}`;
+
+  // Trellis admin username is always "admin" — not stored in the vault
+  return { url, user: 'admin', pass: adminPassword };
+}

package/src/validation.js

@@ -0,0 +1,65 @@
+import { log } from './format.js';
+
+/**
+ * Walk the block tree and collect any blocks where isValid === false.
+ */
+export async function checkBlockValidation(page) {
+  try {
+    return await page.evaluate(() => {
+      const walk = blocks => blocks.flatMap(block => [
+        ...(block.isValid === false
+          ? [{ blockId: block.clientId, blockName: block.name, error: 'Block validation failed' }]
+          : []),
+        ...walk(block.innerBlocks ?? []),
+      ]);
+      return walk(window.wp.data.select('core/block-editor').getBlocks());
+    });
+  } catch (error) {
+    log(`Block validation check error: ${error.message}`, 'yellow');
+    return [];
+  }
+}
+
+/**
+ * Compare the editor's serialized output against the original source.
+ * Whitespace-normalizes both sides before diffing to avoid false positives
+ * from indentation changes, then surfaces up to 5 added/removed lines.
+ */
+export async function compareContent(page, originalContent) {
+  const result = { matches: true, errors: [], warnings: [], savedContent: null };
+
+  try {
+    const savedContent = await page.evaluate(() =>
+      window.wp.data.select('core/editor').getEditedPostContent()
+    );
+    result.savedContent = savedContent;
+
+    const normalize = str => str.replace(/\s+/g, ' ').trim();
+    if (normalize(savedContent) === normalize(originalContent)) return result;
+
+    result.matches = false;
+
+    const origLines  = originalContent.split('\n').map(l => l.trim()).filter(Boolean);
+    const savedLines = savedContent.split('\n').map(l => l.trim()).filter(Boolean);
+
+    const removed = origLines.filter(l => !savedLines.includes(l)).slice(0, 5);
+    const added   = savedLines.filter(l => !origLines.includes(l)).slice(0, 5);
+
+    if (removed.length > 0) {
+      result.errors.push({
+        type: 'content_mismatch',
+        message: `Content removed by editor:\n    ${removed.join('\n    ')}`,
+      });
+    }
+    if (added.length > 0) {
+      result.warnings.push({
+        type: 'content_injected',
+        message: `Content injected by editor:\n    ${added.join('\n    ')}`,
+      });
+    }
+  } catch (error) {
+    result.errors.push({ type: 'comparison_error', message: error.message });
+  }
+
+  return result;
+}