Make the cpx cache layer atomic and concurrent-safe

composer.json

@@ -35,11 +35,13 @@
     },
     "require": {
         "php": "^8.3",
+        "laravel/prompts": "^0.3.21",
         "symfony/console": "^7.4|^8.0"
     },
     "require-dev": {
         "laravel/pao": "^1.1",
         "laravel/pint": "^1.29",
+        "mockery/mockery": "^1.6",
         "pestphp/pest": "^4.7",
         "pestphp/pest-plugin-type-coverage": "^4.0",
         "phpstan/phpstan": "^2.2"

src/Cache/ExecSandboxMetadata.php

@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Cpx\Cache;
+
+class ExecSandboxMetadata
+{
+    /**
+     * @param  list<string>  $packages
+     */
+    public function __construct(
+        public readonly string $key,
+        public array $packages = [],
+        public ?int $lastUpdatedAt = null,
+        public ?int $lastRunAt = null,
+    ) {
+        //
+    }
+
+    public static function rootPath(): string
+    {
+        return cpx_path('.exec_cache');
+    }
+
+    public static function pathFor(string $key): string
+    {
+        return cpx_path(".exec_cache/{$key}");
+    }
+
+    public function path(): string
+    {
+        return self::pathFor($this->key);
+    }
+}

src/Cache/Metadata.php

@@ -4,21 +4,34 @@
 
 namespace Cpx\Cache;
 
+use Closure;
 use Cpx\Packages\Package;
 use Cpx\Support\Arr;
+use Cpx\Support\Filesystem;
+use Cpx\Support\Lock;
 
 class Metadata
 {
+    public const UPDATE_CHECK_INTERVAL = 60 * 60;
+
     private const FILE = '.cpx_metadata.json';
 
+    private const LOCK_FILE = '.cpx_metadata.lock';
+
+    private const VERSION = 2;
+
     /**
      * @param  array<string, PackageMetadata>  $packages
-     * @param  array<string, array{packages?: list<string>, last_updated?: int, last_run?: int}>  $execCache
+     * @param  array<string, ExecSandboxMetadata>  $execCache
+     * @param  array<string, mixed>  $aliases
      */
     protected function __construct(
         public array $packages = [],
         public array $execCache = [],
-    ) {}
+        public array $aliases = [],
+    ) {
+        //
+    }
 
     public static function open(): self
     {
@@ -37,42 +50,71 @@ public static function open(): self
 
         return new self(
             packages: Arr::mapWithKeys(
-                fn (string $key, array $value): array => [
-                    $key => new PackageMetadata(
-                        package: Package::parse($key),
-                        lastUpdatedAt: $value['last_updated'] ?? null,
-                        lastRunAt: $value['last_run'] ?? null,
-                    ),
-                ],
+                function (string $key, mixed $value): array {
+                    if (! is_array($value)) {
+                        return [];
+                    }
+
+                    return [
+                        $key => new PackageMetadata(
+                            package: Package::parse($key),
+                            lastUpdatedAt: self::normalizeTimestamp($value['last_updated'] ?? null),
+                            lastRunAt: self::normalizeTimestamp($value['last_run'] ?? null),
+                        ),
+                    ];
+                },
                 is_array($json['packages'] ?? null) ? $json['packages'] : [],
             ),
-            execCache: is_array($json['execCache'] ?? null) ? $json['execCache'] : [],
+            execCache: Arr::mapWithKeys(
+                function (string $key, mixed $value): array {
+                    if (! is_array($value)) {
+                        return [];
+                    }
+
+                    return [
+                        $key => new ExecSandboxMetadata(
+                            key: $key,
+                            packages: is_array($value['packages'] ?? null) ? array_values($value['packages']) : [],
+                            lastUpdatedAt: self::normalizeTimestamp($value['last_updated'] ?? null),
+                            lastRunAt: self::normalizeTimestamp($value['last_run'] ?? null),
+                        ),
+                    ];
+                },
+                is_array($json['execCache'] ?? null) ? $json['execCache'] : [],
+            ),
+            aliases: is_array($json['aliases'] ?? null) ? $json['aliases'] : [],
         );
     }
 
-    public function recordRun(Package $package): self
+    /**
+     * @template TReturn
+     *
+     * @param  Closure(self): TReturn  $mutator
+     * @return TReturn
+     */
+    public static function transaction(Closure $mutator): mixed
     {
-        $this->forPackage($package)->lastRunAt = date('Y-m-d H:i:s');
+        return Lock::run(cpx_path(self::LOCK_FILE), function () use ($mutator) {
+            $metadata = self::open();
+            $result = $mutator($metadata);
+            $metadata->writeToDisk();
 
-        return $this;
+            return $result;
+        });
     }
 
-    public function recordUpdate(Package $package): self
+    public function recordRun(Package $package): self
     {
-        $this->forPackage($package)->lastUpdatedAt = date('Y-m-d H:i:s');
+        $this->forPackage($package)->lastRunAt = time();
 
         return $this;
     }
 
-    public function save(): void
+    public function recordUpdate(Package $package): self
     {
-        $metadataFile = cpx_path(self::FILE);
-
-        if (! is_dir(dirname($metadataFile))) {
-            mkdir(dirname($metadataFile), 0755, true);
-        }
+        $this->forPackage($package)->lastUpdatedAt = time();
 
-        file_put_contents($metadataFile, json_encode($this->toArray(), JSON_PRETTY_PRINT));
+        return $this;
     }
 
     public function hasPackage(string|Package $package): bool
@@ -86,13 +128,17 @@ public function hasPackage(string|Package $package): bool
 
     /**
      * @return array{
-     *     packages: array<string, array{last_updated: string|null, last_run: string|null}>,
-     *     execCache: array<string, array{packages?: list<string>, last_updated?: int, last_run?: int}>
+     *     version: int,
+     *     aliases: array<string, mixed>,
+     *     packages: array<string, array{last_updated: int|null, last_run: int|null}>,
+     *     execCache: array<string, array{packages: list<string>, last_updated: int|null, last_run: int|null}>
      * }
      */
     public function toArray(): array
     {
         return [
+            'version' => self::VERSION,
+            'aliases' => $this->aliases,
             'packages' => Arr::mapWithKeys(
                 fn (string $key, PackageMetadata $packageMetadata): array => [
                     $packageMetadata->package->fullPackageString() => [
@@ -102,12 +148,41 @@ public function toArray(): array
                 ],
                 $this->packages,
             ),
-            'execCache' => $this->execCache,
+            'execCache' => Arr::mapWithKeys(
+                fn (string $key, ExecSandboxMetadata $sandbox): array => [
+                    $sandbox->key => [
+                        'packages' => $sandbox->packages,
+                        'last_updated' => $sandbox->lastUpdatedAt,
+                        'last_run' => $sandbox->lastRunAt,
+                    ],
+                ],
+                $this->execCache,
+            ),
         ];
     }
 
+    private function writeToDisk(): void
+    {
+        Filesystem::writeAtomic(cpx_path(self::FILE), (string) json_encode($this->toArray(), JSON_PRETTY_PRINT));
+    }
+
     private function forPackage(Package $package): PackageMetadata
     {
         return $this->packages[$package->fullPackageString()] ??= new PackageMetadata($package);
     }
+
+    private static function normalizeTimestamp(int|string|null $value): ?int
+    {
+        if ($value === null || $value === '') {
+            return null;
+        }
+
+        if (is_int($value)) {
+            return $value;
+        }
+
+        $timestamp = strtotime($value);
+
+        return $timestamp === false ? null : $timestamp;
+    }
 }

src/Cache/PackageMetadata.php

@@ -10,7 +10,19 @@ class PackageMetadata
 {
     public function __construct(
         public readonly Package $package,
-        public ?string $lastUpdatedAt = null,
-        public ?string $lastRunAt = null,
-    ) {}
+        public ?int $lastUpdatedAt = null,
+        public ?int $lastRunAt = null,
+    ) {
+        //
+    }
+
+    public function installPath(): string
+    {
+        return $this->package->installPath();
+    }
+
+    public function lastRunForDisplay(): string
+    {
+        return $this->lastRunAt === null ? 'N/A' : date('Y-m-d H:i:s', $this->lastRunAt);
+    }
 }