feat: inventory crud

.cursor/commands/_analyze.md

@@ -0,0 +1 @@
+meticulously catalog and analyze all the changes

.cursor/commands/_in-branch.md

@@ -0,0 +1 @@
+in this branch, compared to the branch it's based on

.cursor/commands/_in-diff.md

@@ -0,0 +1 @@
+in this Git working tree, staged or unstaged

.cursor/commands/_report.md

@@ -0,0 +1 @@
+provide a detailed report but don't make any changes yet.

.cursor/commands/_review.md

@@ -0,0 +1 @@
+review everything thoroughly with a focus on where these fall short of our development, architecture and testing rules

.cursor/commands/create-branch.md

@@ -1,4 +1,5 @@
-Analyze the changes in this Git working tree and create a new branch with a suitable name.
+Meticulously catalog and analyze all the changes in this Git working tree, staged or unstaged
+and create a new branch with a suitable name.
 
 Create the branch only (no commits yet). Use Conventional Commit types as branch prefixes:
 feat/, fix/, docs/, style/, refactor/, perf/, test/, build/, ci/, chore/, revert/.

.cursor/commands/create-commits.md

@@ -1,4 +1,5 @@
-Analyze the changes in this Git working tree and create one or more commits with suitable titles.
+Meticulously catalog and analyze all the changes in this Git working tree, staged or unstaged
+and create one or more commits with suitable titles.
 
 Use Conventional Commits to group related changes into cohesive commits (commits should be independently meaningful).
 

.cursor/rules/01-architecture.mdc

@@ -55,7 +55,7 @@ $service = new MyService(new Dependency());
 
 **Rule:** ALL object creation must use `App::build()` except for value objects, DTOs, and pure data structures.
 
-**Testing Exception:** Direct `Container` instantiation is acceptable in tests to isolate state and avoid shared singleton behavior. Production code must always use `App::build()`.
+**Testing Exception:** Direct instantiation is acceptable in tests to make mocking and isolation simpler. Production code must always use `App::build()`.
 
 ```php
 // ✅ ACCEPTABLE IN TESTS - Isolated container for test isolation

app/Services/InventoryService.php

@@ -0,0 +1,270 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Bigpixelrocket\DeployerPHP\Services;
+
+use Symfony\Component\Filesystem\Filesystem;
+use Symfony\Component\Yaml\Yaml;
+
+/**
+ * Inventory file CRUD operations.
+ *
+ * @example
+ * $inventory = App::build(InventoryService::class);
+ *
+ * // Store values using dot notation
+ * $inventory->set('servers.production.host', 'example.com');
+ * $inventory->set('servers.production.user', 'deployer');
+ *
+ * // Or set entire object at once
+ * $inventory->set('servers.production', ['host' => 'example.com', 'user' => 'deployer']);
+ *
+ * // Retrieve values at any depth
+ * $inventory->get('servers.production.host');  // 'example.com'
+ * $inventory->get('servers.production');       // ['host' => 'example.com', 'user' => 'deployer']
+ * $inventory->get('servers');                  // ['production' => ['host' => 'example.com', 'user' => 'deployer']]
+ * $inventory->get('servers.staging');          // null
+ *
+ * // Check if path exists
+ * if ($inventory->has('servers.production')) {
+ *     // Path exists
+ * }
+ *
+ * // Delete path
+ * $inventory->delete('servers.production');
+ */
+class InventoryService
+{
+    private readonly string $inventoryPath;
+    private readonly string $inventoryDir;
+
+    public function __construct(
+        private readonly Filesystem $filesystem,
+    ) {
+        $this->inventoryPath = rtrim((string) getcwd(), '/').'/.deployer/inventory.yml';
+        $this->inventoryDir = dirname($this->inventoryPath);
+    }
+
+    //
+    // Public
+    // -------------------------------------------------------------------------------
+
+    /**
+     * Set a value using dot notation path.
+     */
+    public function set(string $path, mixed $value): void
+    {
+        $inventory = $this->readInventory();
+        $segments = $this->parsePath($path);
+
+        $this->setByPath($inventory, $segments, $value);
+        $this->writeInventory($inventory);
+    }
+
+    /**
+     * Get a value using dot notation path.
+     */
+    public function get(string $path): mixed
+    {
+        $inventory = $this->readInventory();
+        $segments = $this->parsePath($path);
+
+        return $this->getByPath($inventory, $segments);
+    }
+
+    /**
+     * Get the entire inventory structure.
+     *
+     * @return array<string, mixed>
+     */
+    public function getAll(): array
+    {
+        return $this->readInventory();
+    }
+
+    /**
+     * Check if a path exists using dot notation.
+     */
+    public function has(string $path): bool
+    {
+        $inventory = $this->readInventory();
+        $segments = $this->parsePath($path);
+
+        return $this->hasByPath($inventory, $segments);
+    }
+
+    /**
+     * Delete a value using dot notation path.
+     */
+    public function delete(string $path): void
+    {
+        $inventory = $this->readInventory();
+        $segments = $this->parsePath($path);
+
+        $this->unsetByPath($inventory, $segments);
+        $this->writeInventory($inventory);
+    }
+
+    //
+    // Private
+    // -------------------------------------------------------------------------------
+
+    //
+    // Dot Notation Helpers
+
+    /**
+     * Parse dot notation path into array segments.
+     *
+     * @return array<int, string>
+     */
+    private function parsePath(string $path): array
+    {
+        return explode('.', $path);
+    }
+
+    /**
+     * Get value from nested array using dot notation path segments.
+     *
+     * @param array<string, mixed> $data
+     * @param array<int, string> $segments
+     */
+    private function getByPath(array $data, array $segments): mixed
+    {
+        $current = $data;
+
+        foreach ($segments as $segment) {
+            if (!is_array($current) || !array_key_exists($segment, $current)) {
+                return null;
+            }
+            $current = $current[$segment];
+        }
+
+        return $current;
+    }
+
+    /**
+     * Set value in nested array using dot notation path segments.
+     *
+     * @param array<string, mixed> $data
+     * @param array<int, string> $segments
+     */
+    private function setByPath(array &$data, array $segments, mixed $value): void
+    {
+        $current = &$data;
+
+        foreach ($segments as $segment) {
+            if (!is_array($current)) {
+                $current = [];
+            }
+
+            if (!array_key_exists($segment, $current)) {
+                $current[$segment] = [];
+            }
+
+            $current = &$current[$segment];
+        }
+
+        $current = $value;
+    }
+
+    /**
+     * Check if path exists in nested array using dot notation path segments.
+     *
+     * @param array<string, mixed> $data
+     * @param array<int, string> $segments
+     */
+    private function hasByPath(array $data, array $segments): bool
+    {
+        $current = $data;
+
+        foreach ($segments as $segment) {
+            if (!is_array($current) || !array_key_exists($segment, $current)) {
+                return false;
+            }
+            $current = $current[$segment];
+        }
+
+        return true;
+    }
+
+    /**
+     * Remove path from nested array using dot notation path segments.
+     *
+     * @param array<string, mixed> $data
+     * @param array<int, string> $segments
+     */
+    private function unsetByPath(array &$data, array $segments): bool
+    {
+        if (empty($segments)) {
+            return false;
+        }
+
+        $lastSegment = array_pop($segments);
+        $current = &$data;
+
+        // Navigate to parent of target
+        foreach ($segments as $segment) {
+            if (!is_array($current) || !array_key_exists($segment, $current)) {
+                return false; // Path doesn't exist
+            }
+            $current = &$current[$segment];
+        }
+
+        if (!is_array($current) || !array_key_exists($lastSegment, $current)) {
+            return false; // Target doesn't exist
+        }
+
+        unset($current[$lastSegment]);
+        return true;
+    }
+
+    //
+    // File Operations
+
+    /**
+     * Read inventory YAML into a structured array.
+     *
+     * @return array<string, mixed>
+     */
+    private function readInventory(): array
+    {
+        $path = $this->inventoryPath;
+
+        if (!$this->filesystem->exists($path)) {
+            return [];
+        }
+
+        $raw = $this->filesystem->readFile($path);
+        $parsed = Yaml::parse($raw);
+
+        /** @var array<string, mixed> $result */
+        $result = is_array($parsed) ? $parsed : [];
+        return $result;
+    }
+
+    /**
+     * Persist inventory data to YAML file.
+     *
+     * @param array<string, mixed> $inventory
+     */
+    private function writeInventory(array $inventory): void
+    {
+        $path = $this->inventoryPath;
+
+        if (!$this->filesystem->exists($this->inventoryDir)) {
+            try {
+                $this->filesystem->mkdir($this->inventoryDir, 0775);
+            } catch (\Throwable $e) {
+                throw new \RuntimeException("Unable to create inventory directory: {$this->inventoryDir}", 0, $e);
+            }
+        }
+
+        $yaml = Yaml::dump($inventory, 2, 4, Yaml::DUMP_EMPTY_ARRAY_AS_SEQUENCE);
+        try {
+            $this->filesystem->dumpFile($path, $yaml);
+        } catch (\Throwable $e) {
+            throw new \RuntimeException("Failed to write inventory file at {$path}", 0, $e);
+        }
+    }
+}

tests/TestHelpers.php

@@ -2,6 +2,8 @@
 
 declare(strict_types=1);
 
+use Symfony\Component\Filesystem\Filesystem;
+
 if (!function_exists('setEnv')) {
     /**
      * Set or unset environment variables for testing.
@@ -18,3 +20,54 @@ function setEnv(string $key, ?string $value): void
         }
     }
 }
+
+if (!function_exists('mockFilesystem')) {
+    /**
+     * Create a mock filesystem for testing with comprehensive error simulation.
+     */
+    function mockFilesystem(
+        bool $exists = true,
+        string $content = '',
+        bool $throwOnRead = false,
+        bool $throwOnMkdir = false,
+        bool $throwOnDump = false
+    ): Filesystem {
+        return new class ($exists, $content, $throwOnRead, $throwOnMkdir, $throwOnDump) extends Filesystem {
+            public function __construct(
+                private readonly bool $exists,
+                private readonly string $content,
+                private readonly bool $throwOnRead,
+                private readonly bool $throwOnMkdir,
+                private readonly bool $throwOnDump
+            ) {
+            }
+
+            public function exists(string|iterable $files): bool
+            {
+                return $this->exists;
+            }
+
+            public function readFile(string $filename): string
+            {
+                if ($this->throwOnRead) {
+                    throw new \RuntimeException('Permission denied');
+                }
+                return $this->content;
+            }
+
+            public function mkdir($dirs, int $mode = 0777): void
+            {
+                if ($this->throwOnMkdir) {
+                    throw new \Exception('Permission denied');
+                }
+            }
+
+            public function dumpFile(string $filename, $content): void
+            {
+                if ($this->throwOnDump) {
+                    throw new \Exception('Write failed');
+                }
+            }
+        };
+    }
+}