@imwz/wp-pattern-sentinel 0.2.5 → 0.3.0

package/README.md

@@ -120,6 +120,9 @@ node bin/sentinel.js --concurrency=6 --url=... path/to/patterns/
 | `--keep-page` | `false` | Don't delete draft pages after validation |
 | `--width` | `1280` | Viewport width |
 | `--height` | `800` | Viewport height |
+| `--cache` | `false` | Skip patterns that previously passed with the same file content (see [Pass cache](#pass-cache)) |
+| `--clear-cache` | `false` | Delete `.sentinel-cache.json` and exit (or combine with a path to clear then validate) |
+| `--log` | `false` | Always write `sentinel-<timestamp>.log.json`, even when all patterns pass |
 
 ## Architecture
 
@@ -134,7 +137,60 @@ src/
   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.
+Each worker gets its own authenticated `BrowserContext` so session failures are isolated. Login happens once, then cookies are shared across all contexts — concurrent logins are never attempted.
+
+### Login resilience
+
+If the WordPress login page times out (common on slow local VMs), sentinel retries automatically with exponential backoff:
+
+| Attempt | Wait before retry |
+|---------|-------------------|
+| 1st | — |
+| 2nd | 5 s |
+| 3rd | 15 s |
+| 4th (final) | 30 s |
+
+Credential rejections (wrong password) are not retried — only timeout errors trigger the backoff.
+
+### Real-time output
+
+Each pattern result is printed to the terminal as soon as that worker finishes, rather than buffering everything until the full batch completes. During a long concurrent run you see progress immediately.
+
+### Pass cache
+
+`--cache` stores a `.sentinel-cache.json` file in the working directory. Each entry records the file's content hash and the last pass result:
+
+```json
+{
+  "patterns/main-hero.php": {
+    "hash": "a1b2c3d4e5f6",
+    "passed": true,
+    "checkedAt": "2026-05-16T10:00:00.000Z"
+  }
+}
+```
+
+On subsequent runs, if a pattern file's content hash matches the cached entry **and** it previously passed, the pattern is skipped. If the file has changed (even by one byte), it is re-validated and the cache entry is updated. Failed patterns are always removed from the cache so they are never skipped.
+
+```bash
+# First run — validates all, populates cache
+sentinel --cache --log patterns/
+
+# Later runs — only validates new or changed patterns
+sentinel --cache --log patterns/
+
+# Reset the cache (e.g. after a theme.json change that affects all patterns)
+sentinel --clear-cache
+
+# Clear and immediately re-validate
+sentinel --clear-cache --cache --log patterns/
+```
+
+Commit `.sentinel-cache.json` to track validated state across sessions. Add it to `.gitignore` if you prefer each developer to maintain their own local cache.
+
+### Failure log
+
+When any pattern fails, sentinel automatically writes a `sentinel-<timestamp>.log.json` file in the current working directory and prints the path after the summary. This preserves error details for later inspection without needing to re-run. Use `--log` to write the file even on a fully-passing run.
 
 ## npm publish
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imwz/wp-pattern-sentinel",
-  "version": "0.2.5",
+  "version": "0.3.0",
   "description": "Browser-based WordPress block pattern validator using Playwright",
   "type": "module",
   "engines": {

package/src/args.js

@@ -34,6 +34,10 @@ const ARG_OPTIONS = {
   concurrency:   { type: 'string',  default: '4' },
   width:         { type: 'string',  default: '1280' },
   height:        { type: 'string',  default: '800' },
+  // Persistence
+  cache:         { type: 'boolean', default: false },
+  'clear-cache': { type: 'boolean', default: false },
+  log:           { type: 'boolean', default: false },
 };
 
 /**
@@ -126,6 +130,9 @@ export async function parseArgs(args) {
     headless:    values.headless,
     json:        values.json,
     keepPage:    values['keep-page'],
+    cache:       values.cache,
+    clearCache:  values['clear-cache'],
+    log:         values.log,
     concurrency: Math.max(1, parseInt(values.concurrency, 10)),
     viewport: {
       width:  parseInt(values.width,  10),

package/src/format.js

@@ -28,18 +28,19 @@ export function formatResult(result) {
   return lines.join('\n');
 }
 
-export function printSummary(results) {
+export function printSummary(results, skipped = 0) {
   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);
+  const avgMs        = results.length > 0 ? Math.round(totalMs / results.length) : 0;
 
   log('\n' + '='.repeat(60));
   log('Validation Summary', 'cyan');
   log('='.repeat(60));
   log(`Patterns  : ${results.length}`);
+  if (skipped > 0) log(`Skipped   : ${skipped} (cached)`, 'gray');
   log(`Passed    : ${passed}`,       passed      > 0 ? 'green'  : 'gray');
   log(`Failed    : ${failed}`,       failed      > 0 ? 'red'    : 'gray');
   log(`Errors    : ${totalErrors}`,  totalErrors > 0 ? 'red'    : 'gray');

package/src/login.js

@@ -1,40 +1,63 @@
 import { log } from './format.js';
 
+const RETRY_DELAYS = [5_000, 15_000, 30_000]; // ms between attempts 1→2, 2→3, 3→4
+
 export async function loginToWordPress(page, adminUrl, user, pass) {
-  try {
-    // Navigate to the editor — WordPress redirects to wp-login.php if unauthenticated,
-    // with redirect_to preserving the editor URL (important for multisite subsite context).
-    await page.goto(`${adminUrl}/wp-admin/post-new.php?post_type=page`, {
-      waitUntil: 'domcontentloaded',
-      timeout: 60000,
-    });
-
-    // Already logged in — editor loaded directly
-    if (await page.locator('.edit-post-layout, .editor-styles-wrapper').count() > 0) {
-      return true;
+  for (let attempt = 0; attempt <= RETRY_DELAYS.length; attempt++) {
+    if (attempt > 0) {
+      const delay = RETRY_DELAYS[attempt - 1];
+      log(`  Login timeout — waiting ${delay / 1000}s before retry ${attempt}/${RETRY_DELAYS.length}...`, 'yellow');
+      await new Promise(resolve => setTimeout(resolve, delay));
     }
 
-    // Wait for the login form to be ready before filling
-    await page.waitForSelector('#user_login', { state: 'visible', timeout: 30000 });
-    await page.fill('#user_login', user);
-    await page.fill('#user_pass', pass);
-
-    // Start listening for navigation BEFORE clicking — avoids missing the redirect
-    await Promise.all([
-      page.waitForNavigation({ waitUntil: 'domcontentloaded', timeout: 60000 }),
-      page.click('#wp-submit'),
-    ]);
-
-    const loggedIn = page.url().includes('/wp-admin/') && !page.url().includes('wp-login.php');
-    if (!loggedIn) {
-      const error = await page.textContent('#login_error').catch(() => null);
-      log(`Login failed: ${error?.trim() ?? 'unexpected URL after submit: ' + page.url()}`, 'red');
-      return false;
+    try {
+      const result = await attemptLogin(page, adminUrl, user, pass);
+      return result; // true = success, false = credential error (don't retry)
+    } catch (err) {
+      const shortMsg = err.message.split('\n')[0];
+      if (attempt < RETRY_DELAYS.length) {
+        log(`  Login attempt ${attempt + 1} timed out: ${shortMsg}`, 'yellow');
+      } else {
+        log(`Login failed after ${RETRY_DELAYS.length + 1} attempts: ${shortMsg}`, 'red');
+        return false;
+      }
     }
+  }
+
+  return false;
+}
+
+async function attemptLogin(page, adminUrl, user, pass) {
+  // Navigate to the editor — WordPress redirects to wp-login.php if unauthenticated,
+  // with redirect_to preserving the editor URL (important for multisite subsite context).
+  await page.goto(`${adminUrl}/wp-admin/post-new.php?post_type=page`, {
+    waitUntil: 'domcontentloaded',
+    timeout: 60000,
+  });
 
+  // Already logged in — editor loaded directly
+  if (await page.locator('.edit-post-layout, .editor-styles-wrapper').count() > 0) {
     return true;
-  } catch (error) {
-    log(`Login failed: ${error.message}`, 'red');
+  }
+
+  // Wait for the login form to be ready before filling
+  await page.waitForSelector('#user_login', { state: 'visible', timeout: 30000 });
+  await page.fill('#user_login', user);
+  await page.fill('#user_pass', pass);
+
+  // Start listening for navigation BEFORE clicking — avoids missing the redirect
+  await Promise.all([
+    page.waitForNavigation({ waitUntil: 'domcontentloaded', timeout: 60000 }),
+    page.click('#wp-submit'),
+  ]);
+
+  const loggedIn = page.url().includes('/wp-admin/') && !page.url().includes('wp-login.php');
+  if (!loggedIn) {
+    const error = await page.textContent('#login_error').catch(() => null);
+    // Credential error — no point retrying
+    log(`Login rejected: ${error?.trim() ?? 'unexpected URL after submit: ' + page.url()}`, 'red');
     return false;
   }
+
+  return true;
 }

package/src/main.js

@@ -2,6 +2,7 @@ import { chromium } from 'playwright';
 import PQueue from 'p-queue';
 import path from 'path';
 import fs from 'fs';
+import crypto from 'crypto';
 import { parseArgs, resolveFiles } from './args.js';
 import { loginToWordPress } from './login.js';
 import {
@@ -14,15 +15,78 @@ import {
 import { checkBlockValidation, compareContent } from './validation.js';
 import { log, formatResult, printSummary } from './format.js';
 
+const CACHE_FILE = '.sentinel-cache.json';
+
+function loadCache() {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(process.cwd(), CACHE_FILE), 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+async function saveCache(cache) {
+  try {
+    await fs.promises.writeFile(
+      path.join(process.cwd(), CACHE_FILE),
+      JSON.stringify(cache, null, 2)
+    );
+  } catch { /* ignore */ }
+}
+
+function hashContent(content) {
+  return crypto.createHash('sha256').update(content).digest('hex').slice(0, 12);
+}
+
 export async function main() {
   const options = await parseArgs(process.argv.slice(2));
-  const files   = resolveFiles(options.files);
+
+  if (options.clearCache) {
+    try {
+      fs.unlinkSync(path.join(process.cwd(), CACHE_FILE));
+      log('Cache cleared.', 'green');
+    } catch {
+      log('No cache file found.', 'gray');
+    }
+    if (options.files.length === 0) process.exit(0);
+  }
+
+  let files     = resolveFiles(options.files);
 
   if (files.length === 0) {
     log('No pattern files found.', 'red');
     process.exit(1);
   }
 
+  // Skip patterns that previously passed with the same file content.
+  const cache = options.cache ? loadCache() : {};
+  const skipped = [];
+  if (options.cache) {
+    const pending = [];
+    for (const file of files) {
+      try {
+        const content = fs.readFileSync(file, 'utf8');
+        const key     = path.relative(process.cwd(), file);
+        if (cache[key]?.passed && cache[key]?.hash === hashContent(content)) {
+          skipped.push(file);
+        } else {
+          pending.push(file);
+        }
+      } catch {
+        pending.push(file);
+      }
+    }
+    files = pending;
+    if (skipped.length > 0) {
+      log(`Skipping ${skipped.length} previously-passed pattern(s) (cached)`, 'gray');
+    }
+  }
+
+  if (files.length === 0) {
+    log('All patterns already validated — nothing to do.', 'green');
+    process.exit(0);
+  }
+
   log(`\nFound ${files.length} pattern(s) — concurrency: ${options.concurrency}`, 'cyan');
 
   const browser = await chromium.launch({
@@ -60,10 +124,17 @@ export async function main() {
   const queue = new PQueue({ concurrency: options.concurrency });
   let idx = 0;
 
-  // Push ALL tasks without awaiting — this is what makes workers run in parallel
+  // Push ALL tasks without awaiting — workers run in parallel.
+  // Print each result immediately as it finishes (real-time feedback).
   const promises = files.map(file => {
     const context = contexts[idx++ % options.concurrency];
-    return queue.add(() => validatePatternFile(file, options, context));
+    return queue.add(async () => {
+      const result = await validatePatternFile(file, options, context);
+      if (!options.json) {
+        console.log(formatResult(result));
+      }
+      return result;
+    });
   });
 
   const results = await Promise.all(promises);
@@ -73,12 +144,32 @@ export async function main() {
 
   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);
+  printSummary(results, skipped.length);
+
+  // Update cache with results from this run.
+  if (options.cache) {
+    for (const result of results) {
+      const key = path.relative(process.cwd(), result.patternPath);
+      if (result.passed) {
+        cache[key] = { hash: result.hash, passed: true, checkedAt: new Date().toISOString() };
+      } else {
+        delete cache[key];
+      }
+    }
+    await saveCache(cache);
+    log(`  Cache updated → ${CACHE_FILE}`, 'gray');
+  }
+
+  // Write a log file on failure, or always when --log is set.
+  const hasFailed = results.some(r => !r.passed);
+  if (hasFailed || options.log) {
+    const logPath = await writeLogFile(results);
+    if (logPath) log(`  Log saved → ${logPath}`, 'gray');
+  }
+
+  process.exit(hasFailed ? 1 : 0);
 }
 
 async function validatePatternFile(patternPath, options, context) {
@@ -91,12 +182,12 @@ async function validatePatternFile(patternPath, options, context) {
   try {
     fileContent = await fs.promises.readFile(patternPath, 'utf8');
   } catch (error) {
-    return fail(patternName, startTime, 'file_error', error.message);
+    return fail(patternName, patternPath, startTime, 'file_error', error.message);
   }
 
   const blockContent = extractBlockContent(fileContent);
   if (!blockContent) {
-    return fail(patternName, startTime, 'extraction_error', 'Could not extract block content from file');
+    return fail(patternName, patternPath, startTime, 'extraction_error', 'Could not extract block content from file');
   }
 
   const page = await context.newPage();
@@ -105,12 +196,12 @@ async function validatePatternFile(patternPath, options, context) {
   try {
     const pageId = await createDraftPage(page, options.adminUrl);
     if (pageId === null) {
-      return fail(patternName, startTime, 'page_creation_error', 'Failed to create test page');
+      return fail(patternName, patternPath, startTime, 'page_creation_error', 'Failed to create test page');
     }
 
     if (!(await insertPatternIntoEditor(page, blockContent))) {
       await deletePage(page, options.adminUrl, pageId);
-      return fail(patternName, startTime, 'insertion_error', 'Failed to insert pattern into editor');
+      return fail(patternName, patternPath, startTime, 'insertion_error', 'Failed to insert pattern into editor');
     }
 
     const saveResult  = await savePage(page);
@@ -133,6 +224,8 @@ async function validatePatternFile(patternPath, options, context) {
 
     return {
       pattern:      patternName,
+      patternPath,
+      hash:         hashContent(fileContent),
       passed:       saveResult.success && comparison.matches && blockErrors.length === 0,
       errors:       saveResult.errors,
       warnings:     saveResult.warnings,
@@ -142,18 +235,42 @@ async function validatePatternFile(patternPath, options, context) {
 
   } catch (error) {
     log(`Unexpected error — ${patternName}: ${error.message}`, 'red');
-    return fail(patternName, startTime, 'validation_error', error.message);
+    return fail(patternName, patternPath, startTime, 'validation_error', error.message);
   } finally {
     await page.close();
   }
 }
 
-function fail(pattern, startTime, type, message) {
+function fail(pattern, patternPath, startTime, type, message) {
   return {
     pattern,
+    patternPath,
+    hash:     null,
     passed:   false,
     errors:   [{ type, message }],
     warnings: [],
     duration: Date.now() - startTime,
   };
 }
+
+async function writeLogFile(results) {
+  try {
+    const now = new Date();
+    const ts  = now.toISOString().replace(/[:.]/g, '-').slice(0, 19);
+    const logPath = path.join(process.cwd(), `sentinel-${ts}.log.json`);
+    const payload = {
+      timestamp: now.toISOString(),
+      results: results.map(r => ({
+        pattern:  r.pattern,
+        passed:   r.passed,
+        duration: r.duration,
+        errors:   r.errors,
+        warnings: r.warnings,
+      })),
+    };
+    await fs.promises.writeFile(logPath, JSON.stringify(payload, null, 2));
+    return logPath;
+  } catch {
+    return null;
+  }
+}