From 2528c56f34668c81063444816db8ef0523202ba2 Mon Sep 17 00:00:00 2001
From: Olivier Gorzalka <olivier@amphibee.fr>
Date: Mon, 26 Oct 2026 17:17:17 +0100
Subject: [PATCH] fix: named exception for WP-CLI being unavailable (CONV-10)

The Security patterns gate passes for this package: it no longer needs to be listed in observed.
---
 .harness.json                                  |  3 +--
 CHANGELOG.md                                   |  4 ++++
 src/Domain/Exceptions/WpCliUnavailable.php     | 18 ++++++++++++++++++
 src/Infrastructure/Adapters/WpCliAdapter.php   |  3 ++-
 .../Domain/Exceptions/WpCliUnavailableTest.php | 13 +++++++++++++
 5 files changed, 38 insertions(+), 3 deletions(-)
 create mode 100644 src/Domain/Exceptions/WpCliUnavailable.php
 create mode 100644 tests/Unit/Domain/Exceptions/WpCliUnavailableTest.php

diff --git a/.harness.json b/.harness.json
index 48eb33c..ca9fd08 100644
--- a/.harness.json
+++ b/.harness.json
@@ -11,7 +11,6 @@
     "observed": [
         "Code style",
         "Rector",
-        "Dependency analysis",
-        "Security patterns"
+        "Dependency analysis"
     ]
 }
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 072e128..dd198b1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- Registering a command outside WP-CLI throws the named `WpCliUnavailable` exception instead of a bare `\RuntimeException`. It extends `\RuntimeException`, and the message keeps its `WP-CLI is not available` prefix, followed by how to avoid it
+
 ## [0.1.1] - 2026-10-13
 
 ### Fixed
diff --git a/src/Domain/Exceptions/WpCliUnavailable.php b/src/Domain/Exceptions/WpCliUnavailable.php
new file mode 100644
index 0000000..58c9273
--- /dev/null
+++ b/src/Domain/Exceptions/WpCliUnavailable.php
@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pollora\WpCli\Domain\Exceptions;
+
+use RuntimeException;
+
+/**
+ * Thrown when a command is registered outside a WP-CLI process.
+ */
+final class WpCliUnavailable extends RuntimeException
+{
+    public static function whenRegisteringACommand(): self
+    {
+        return new self('WP-CLI is not available. Register commands from code that runs under `wp`, or check the adapter with isAvailable() first.');
+    }
+}
diff --git a/src/Infrastructure/Adapters/WpCliAdapter.php b/src/Infrastructure/Adapters/WpCliAdapter.php
index 7e4cec3..a8e1d37 100644
--- a/src/Infrastructure/Adapters/WpCliAdapter.php
+++ b/src/Infrastructure/Adapters/WpCliAdapter.php
@@ -4,6 +4,7 @@
 
 namespace Pollora\WpCli\Infrastructure\Adapters;
 
+use Pollora\WpCli\Domain\Exceptions\WpCliUnavailable;
 use WP_CLI;
 
 /**
@@ -36,7 +37,7 @@ public function isAvailable(): bool
     public function addCommand(string $name, string|array|object $handler, array $args = []): void
     {
         if (! $this->isAvailable()) {
-            throw new \RuntimeException('WP-CLI is not available');
+            throw WpCliUnavailable::whenRegisteringACommand();
         }
 
         $this->validateHandler($handler);
diff --git a/tests/Unit/Domain/Exceptions/WpCliUnavailableTest.php b/tests/Unit/Domain/Exceptions/WpCliUnavailableTest.php
new file mode 100644
index 0000000..eb5d259
--- /dev/null
+++ b/tests/Unit/Domain/Exceptions/WpCliUnavailableTest.php
@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+use Pollora\WpCli\Domain\Exceptions\WpCliUnavailable;
+
+it('says WP-CLI is missing and what to do about it', function (): void {
+    $exception = WpCliUnavailable::whenRegisteringACommand();
+
+    expect($exception)->toBeInstanceOf(RuntimeException::class)
+        ->and($exception->getMessage())->toStartWith('WP-CLI is not available')
+        ->and($exception->getMessage())->toContain('isAvailable()');
+});