release: v13.34.0-beta.2

CHANGELOG.md

@@ -5,7 +5,21 @@ All notable changes to the Pollora framework will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased](https://github.com/Pollora/framework/compare/v13.34.0-beta...develop)
+## [Unreleased](https://github.com/Pollora/framework/compare/v13.34.0-beta.2...develop)
+
+## [v13.34.0-beta.2](https://github.com/Pollora/framework/compare/v13.34.0-beta...v13.34.0-beta.2) - 2026-09-30
+
+### Added
+- `pollora:doctor`: checks a project for the failures that stay silent — the site renders, the command exits 0 — and prints, under each, the command that fixes it. Each check comes from a failure met in practice: WordPress core not patched or `__()` not Pollora's; `patches.lock.json` missing or older than the framework's patches; `.env` names Pollora does not read (`DB_NAME`, `WP_HOME`…) or MySQL settings on a sqlite connection; configuration or routes cached outside production; classes missing from the discovery cache; for the theme, every Pollora plugin and every enabled module: a build missing, written to another folder than Pollora reads, or a hot file pointing at a dev server that is stopped or not exposed, a directory symlinked under another name, `%theme_*%`/`%plugin_*%` placeholders or `.stub` files left from a copied template, blocks still in the legacy `resources/blocks`; pattern files WordPress never registers or has not cached; `Route::wp()` routes answering in place of a block theme's templates. `--json` for scripts; exits 1 on an error
+- The same checks in WordPress's **Site Health** (Tools › Site Health), with a "Pollora" badge, plus one that only a web request can make: every block of the theme, the Pollora plugins and the modules is registered. That is the boot a visitor gets — blocks were once registered under WP-CLI but not over HTTP, which a console check would have passed
+
+### Fixed
+- Deleting a navigation menu (`wp menu delete`, or the Menus screen) raised a `TypeError` once the menu was already gone: `delete_nav_menu` is the `delete_{$taxonomy}` hook, which passes the term ID first, and the listener expected a `WP_Term`. `MenuDeleted` now receives the menu WordPress copied before deleting it
+- While Vite ran hot, its client was enqueued with WordPress's version appended (`@vite/client?ver=7.1.2`). The modules Vite serves import `/@vite/client` by its bare URL, so the browser loaded the client twice, as two modules with two HMR connections. It is enqueued with no version, like the entries (regression from v13.34.0-beta)
+- On a branch install (`dev-develop`, `13.x-dev`), Site Health and the admin notice announced "Pollora 13.4.4 is available": `version_compare()` ranks a branch name below every release. A development build is no longer compared with releases — Site Health says it is one, the notice stays silent — and the dashboard, the admin menu badge and `pollora:status` share that one rule, which they each duplicated and missed `13.x-dev`. Site Health's info tab now labels the compared version "Latest stable version", since pre-releases are not counted
+
+### Changed
+- `pollora:make:theme` activates the generated theme only where the site needs one. A site with no usable theme — a first install — gets it without a question; a site that already has one keeps it unless the answer is "yes", now the default "no", so `--no-interaction` never replaces a working theme. `--activate` and `--no-activate` settle it without asking, and `pollora:install` passes `--activate`. Activation goes through `switch_theme()`, which fires `switch_theme` and `after_switch_theme`; the options were written directly before, so those hooks never ran
 
 ## [v13.34.0-beta](https://github.com/Pollora/framework/compare/v13.32.0-beta.9...v13.34.0-beta) - 2026-09-29
 

src/Asset/Infrastructure/Services/AssetEnqueuer.php

@@ -395,7 +395,9 @@ protected function loadViteClient(string $hook): void
                 $url = $this->viteManager instanceof ViteManager ? $this->viteManager->clientUrl() : '';
 
                 if ($url !== '') {
-                    wp_enqueue_script_module('vite-client/'.md5($url), $url);
+                    // No version: the modules Vite serves import /@vite/client by its bare URL,
+                    // and a ?ver= copy would be a second client, with its own HMR connection.
+                    wp_enqueue_script_module('vite-client/'.md5($url), $url, [], null);
                 }
             }, 1);
 

src/Dashboard/Domain/Services/SystemInfoCollector.php

@@ -135,14 +135,15 @@ private function collectLaravelLocale(): string
     }
 
     /**
-     * @return array{current: ?string, latest: ?string, update_available: bool}
+     * @return array{current: ?string, latest: ?string, update_available: bool, development: bool}
      */
     public function collectFrameworkInfo(): array
     {
         return [
             'current' => $this->versionComparator->getCurrentVersion(),
             'latest' => $this->versionComparator->getLatestVersion(),
             'update_available' => $this->versionComparator->isUpdateAvailable(),
+            'development' => $this->versionComparator->isDevelopmentBuild(),
         ];
     }
 

src/Dashboard/Infrastructure/Providers/DashboardServiceProvider.php

@@ -87,11 +87,7 @@ private function countNotifications(): int
         $count = 0;
 
         try {
-            $comparator = $this->app->make(VersionComparator::class);
-            $current = $comparator->getCurrentVersion();
-            $isDev = is_string($current) && str_starts_with($current, 'dev-');
-
-            if (! $isDev && $comparator->isUpdateAvailable()) {
+            if ($this->app->make(VersionComparator::class)->isUpdateAvailable()) {
                 $count++;
             }
         } catch (\Throwable) {

src/Dashboard/UI/Console/StatusCommand.php

@@ -68,14 +68,14 @@ private function renderTranslations(array $translations): void
     }
 
     /**
-     * @param  array{current: ?string, latest: ?string, update_available: bool}  $framework
+     * @param  array{current: ?string, latest: ?string, update_available: bool, development: bool}  $framework
      */
     private function renderFrameworkStatus(array $framework): void
     {
         $current = $framework['current'] ?? 'unknown';
         $latest = $framework['latest'] ?? 'unknown';
         $updateAvailable = $framework['update_available'];
-        $isDev = is_string($current) && str_starts_with($current, 'dev-');
+        $isDev = $framework['development'];
 
         if ($isDev) {
             $this->line(sprintf('Pollora %s (latest stable: v%s)', $current, $latest));

src/Dashboard/UI/Http/DashboardController.php

@@ -121,13 +121,13 @@ private function renderStyles(): void
     }
 
     /**
-     * @param  array{current: ?string, latest: ?string, update_available: bool}  $framework
+     * @param  array{current: ?string, latest: ?string, update_available: bool, development: bool}  $framework
      */
     private function renderHeader(array $framework): void
     {
         $current = $framework['current'] ?? __('Unknown', 'pollora');
         $updateAvailable = $framework['update_available'];
-        $isDev = is_string($current) && str_starts_with($current, 'dev-');
+        $isDev = $framework['development'];
 
         $logoPath = dirname(__DIR__, 4).'/resources/images/pollora-logo.svg';
 

src/Discovery/Infrastructure/Services/DiscoveryCacheManager.php

@@ -130,6 +130,46 @@ public function clearCache(iterable $locations): void
         }
     }
 
+    /**
+     * Classes on disk that the cached entry for a location does not list.
+     *
+     * They stay invisible to discovery — no hook, no post type, no route — until
+     * the cache is cleared, and nothing says so. Null when the location has no
+     * cached entry, or the cache is off, since then discovery reads the disk.
+     *
+     * @return list<string>|null
+     */
+    public function classesMissingFromCache(DiscoveryLocationInterface $location): ?array
+    {
+        if (! $this->shouldUseCache()) {
+            return null;
+        }
+
+        $cacheId = $this->generateCacheId($location);
+
+        if (! $this->cacheDriver->has($cacheId)) {
+            return null;
+        }
+
+        $names = static fn (array $structures): array => array_map(
+            static fn (mixed $structure): string => is_object($structure) && method_exists($structure, 'getFcqn') ? $structure->getFcqn() : (string) $structure,
+            $structures,
+        );
+
+        return array_values(array_diff(
+            $names(Discover::in($location->getPath())->full()->get()),
+            $names($this->cacheDriver->get($cacheId)),
+        ));
+    }
+
+    /**
+     * Whether discovery reads through a persistent cache (it does not in debug mode).
+     */
+    public function isCacheEnabled(): bool
+    {
+        return $this->shouldUseCache();
+    }
+
     /**
      * Get the cache driver instance.
      */

src/Doctor/Application/Services/Doctor.php

@@ -0,0 +1,63 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pollora\Doctor\Application\Services;
+
+use Pollora\Doctor\Domain\Contracts\CheckInterface;
+use Pollora\Doctor\Domain\Enums\RunContext;
+use Pollora\Doctor\Domain\Models\CheckResult;
+use Throwable;
+
+/**
+ * Runs the checks that belong to a context.
+ *
+ * A check that throws is reported as an error of that check, with the exception's
+ * message: one broken check must not hide the verdict of all the others.
+ */
+final readonly class Doctor
+{
+    /**
+     * @param  iterable<CheckInterface>  $checks
+     */
+    public function __construct(private iterable $checks) {}
+
+    /**
+     * @return list<CheckInterface>
+     */
+    public function checksFor(RunContext $context): array
+    {
+        $checks = [];
+
+        foreach ($this->checks as $check) {
+            if (in_array($context, $check->runsIn(), true)) {
+                $checks[] = $check;
+            }
+        }
+
+        return $checks;
+    }
+
+    public function runCheck(CheckInterface $check, RunContext $context): CheckResult
+    {
+        try {
+            return $check->run($context);
+        } catch (Throwable $throwable) {
+            return CheckResult::error(
+                'The check itself failed: '.$throwable->getMessage(),
+                [$throwable::class.' in '.$throwable->getFile().':'.$throwable->getLine()],
+            );
+        }
+    }
+
+    /**
+     * @return list<array{check: CheckInterface, result: CheckResult}>
+     */
+    public function run(RunContext $context): array
+    {
+        return array_map(
+            fn (CheckInterface $check): array => ['check' => $check, 'result' => $this->runCheck($check, $context)],
+            $this->checksFor($context),
+        );
+    }
+}

src/Doctor/Domain/Contracts/CheckInterface.php

@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pollora\Doctor\Domain\Contracts;
+
+use Pollora\Doctor\Domain\Enums\RunContext;
+use Pollora\Doctor\Domain\Models\CheckResult;
+
+/**
+ * One thing `pollora:doctor` and Site Health look at.
+ *
+ * A check earns its place by naming a failure that has happened and stays silent
+ * — the site renders, the command exits 0 — and by saying how to fix it. It
+ * reads; it never writes, and never requests the site over HTTP.
+ */
+interface CheckInterface
+{
+    /** Stable identifier, kebab-case: the key of the JSON output and of the Site Health test. */
+    public function id(): string;
+
+    /** What is checked, for a person. */
+    public function label(): string;
+
+    /**
+     * Where the check can reach a verdict it can stand behind.
+     *
+     * @return list<RunContext>
+     */
+    public function runsIn(): array;
+
+    public function run(RunContext $context): CheckResult;
+}

src/Doctor/Domain/Enums/CheckStatus.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pollora\Doctor\Domain\Enums;
+
+/**
+ * The verdict of one doctor check.
+ *
+ * Skipped is a verdict of its own, never folded into Ok: a check that could not
+ * run says so, rather than passing a site it never looked at.
+ */
+enum CheckStatus: string
+{
+    case Ok = 'ok';
+    case Warning = 'warning';
+    case Error = 'error';
+    case Skipped = 'skipped';
+}

src/Doctor/Domain/Enums/RunContext.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pollora\Doctor\Domain\Enums;
+
+/**
+ * Where a check runs.
+ *
+ * Some failures only exist in a web request — blocks registered under WP-CLI but
+ * not over HTTP, once — so those checks run in WordPress's Site Health, never in
+ * the console, where they would pass a broken site.
+ */
+enum RunContext: string
+{
+    case Console = 'console';
+    case Http = 'http';
+}

src/Doctor/Domain/Models/CheckResult.php

@@ -0,0 +1,66 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pollora\Doctor\Domain\Models;
+
+use Pollora\Doctor\Domain\Enums\CheckStatus;
+
+/**
+ * What a check found: a one-line summary, the details that prove it, and, when
+ * something is wrong, what to do about it.
+ */
+final readonly class CheckResult
+{
+    /**
+     * @param  list<string>  $details
+     */
+    private function __construct(
+        public CheckStatus $status,
+        public string $summary,
+        public array $details = [],
+        public ?string $fix = null,
+    ) {}
+
+    /**
+     * @param  list<string>  $details
+     */
+    public static function ok(string $summary, array $details = []): self
+    {
+        return new self(CheckStatus::Ok, $summary, $details);
+    }
+
+    /**
+     * @param  list<string>  $details
+     */
+    public static function warning(string $summary, array $details = [], ?string $fix = null): self
+    {
+        return new self(CheckStatus::Warning, $summary, $details, $fix);
+    }
+
+    /**
+     * @param  list<string>  $details
+     */
+    public static function error(string $summary, array $details = [], ?string $fix = null): self
+    {
+        return new self(CheckStatus::Error, $summary, $details, $fix);
+    }
+
+    public static function skipped(string $reason): self
+    {
+        return new self(CheckStatus::Skipped, $reason);
+    }
+
+    /**
+     * @return array{status: string, summary: string, details: list<string>, fix: ?string}
+     */
+    public function toArray(): array
+    {
+        return [
+            'status' => $this->status->value,
+            'summary' => $this->summary,
+            'details' => $this->details,
+            'fix' => $this->fix,
+        ];
+    }
+}