fix: resolve OpenAPI spec to absolute path and add port check

- Fixes 500 errors by resolving the specification path to an absolute path before starting the mock server.
- Adds pre-start port availability check to provide clearer error messages for port conflicts.
- Includes validation for the specification file during module initialization.
- Updates GEMINI.md with lessons learned.

Author: Fahl-Design

GEMINI.md

@@ -64,3 +64,15 @@ composer cs:fix             # Fix coding standards
 *   `phpstan.neon`: PHPStan configuration (Level 8).
 *   `.php-cs-fixer.php`: Coding style rules.
 *   `grumphp.yml`: Automation task definitions.
+
+## Lessons Learned & Troubleshooting
+
+### Absolute Path Resolution for OpenAPI Specifications
+The mock server process is started with its own `vendor` directory as the working directory (`cwd`) to facilitate binary execution. This means any relative paths for the `OPENAPI_SPEC` environment variable will be resolved against that library path, leading to `500 Internal Server Error` (CONFIG_ERROR) if the specification is not found.
+- **Rule:** Always resolve the `spec` configuration to an **absolute path** (using `realpath()`) before passing it to the server process.
+
+### Port Availability
+To prevent confusing errors where the mock server seems to be running but does not behave as expected (e.g., if another process is already listening on the same port), the module now performs a pre-start check.
+- **Implementation:** `fsockopen()` is used to verify that the configured port is free before attempting to start the built-in PHP server.
+- **Behavior:** A descriptive `RuntimeException` is thrown if the port is already in use.
+

src/OpenApiServerMock.php

@@ -54,6 +54,14 @@ public function _initialize(): void
 
         if ($this->config['startServer']) {
             $this->validatePath((string) $this->config['path']);
+            $this->validateSpec((string) $this->config['spec']);
+        }
+    }
+
+    private function validateSpec(string $spec): void
+    {
+        if (empty($spec) || !file_exists($spec)) {
+            throw new ModuleConfigException($this, "OpenAPI specification file not found at '{$spec}'.");
         }
     }
 
@@ -119,6 +127,10 @@ public function _afterSuite(): void
 
     protected function startMockServer(): void
     {
+        if ($this->isPortInUse()) {
+            throw new RuntimeException("Port {$this->config['port']} is already in use. Cannot start mock server.");
+        }
+
         $binPath = $this->config['path'] . '/bin/openapi-mock-server';
         if (!file_exists($binPath)) {
             $binPath = $this->config['path'] . '/public/index.php';
@@ -129,8 +141,13 @@ protected function startMockServer(): void
             throw new RuntimeException('PHP executable not found.');
         }
 
+        $specPath = (string) $this->config['spec'];
+        if (file_exists($specPath)) {
+            $specPath = (string) realpath($specPath);
+        }
+
         $command = [$phpBinary, '-S', "{$this->config['host']}:{$this->config['port']}", $binPath];
-        $env     = ['OPENAPI_SPEC' => (string) $this->config['spec']];
+        $env     = ['OPENAPI_SPEC' => $specPath];
 
         $this->process = new Process($command, (string) $this->config['path'], $env);
         $this->process->start();
@@ -141,6 +158,18 @@ protected function startMockServer(): void
         }
     }
 
+    private function isPortInUse(): bool
+    {
+        $fp = @fsockopen($this->config['host'], (int) $this->config['port'], $errno, $errstr, 0.1);
+        if ($fp) {
+            fclose($fp);
+
+            return true;
+        }
+
+        return false;
+    }
+
     private function waitForServer(): bool
     {
         $start = time();