feat(admin): add first-admin bootstrap command

app/Console/Commands/BootstrapFirstAdmin.php

@@ -0,0 +1,84 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Models\User;
+use Illuminate\Console\Attributes\Description;
+use Illuminate\Console\Attributes\Signature;
+use Illuminate\Console\Command;
+use Silber\Bouncer\BouncerFacade as Bouncer;
+
+#[Signature('app:bootstrap-first-admin {email? : Existing user email to promote}')]
+#[Description('Create or promote the first admin user')]
+class BootstrapFirstAdmin extends Command
+{
+    public function handle(): int
+    {
+        $email = $this->argument('email');
+
+        if (is_string($email) && $email !== '') {
+            return $this->promoteExistingUser($email);
+        }
+
+        return $this->createFirstAdmin();
+    }
+
+    protected function createFirstAdmin(): int
+    {
+        $user = User::query()->first();
+
+        if ($user === null) {
+            $this->components->error('No users exist yet. Create a user first, then promote it with the email argument.');
+
+            return self::FAILURE;
+        }
+
+        $this->ensureAdminRoleExists();
+
+        if ($user->isAn('admin')) {
+            $this->components->info("The first user, {$user->email}, is already an admin.");
+
+            return self::SUCCESS;
+        }
+
+        $user->assign('admin');
+        Bouncer::refreshFor($user);
+
+        $this->components->info("Promoted {$user->email} to admin.");
+
+        return self::SUCCESS;
+    }
+
+    protected function promoteExistingUser(string $email): int
+    {
+        $user = User::query()->where('email', $email)->first();
+
+        if ($user === null) {
+            $this->components->error("No user was found for {$email}.");
+
+            return self::FAILURE;
+        }
+
+        $this->ensureAdminRoleExists();
+
+        if ($user->isAn('admin')) {
+            $this->components->info("{$user->email} is already an admin.");
+
+            return self::SUCCESS;
+        }
+
+        $user->assign('admin');
+        Bouncer::refreshFor($user);
+
+        $this->components->info("Promoted {$user->email} to admin.");
+
+        return self::SUCCESS;
+    }
+
+    protected function ensureAdminRoleExists(): void
+    {
+        Bouncer::role()->firstOrCreate([
+            'name' => 'admin',
+        ]);
+    }
+}

tests/Feature/Admin/BootstrapFirstAdminCommandTest.php

@@ -0,0 +1,31 @@
+<?php
+
+use App\Models\User;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+
+uses(RefreshDatabase::class);
+
+it('promotes the first user when no admin exists', function (): void {
+    $user = User::factory()->create();
+
+    $this->artisan('app:bootstrap-first-admin')
+        ->assertExitCode(0);
+
+    expect($user->fresh()->isAn('admin'))->toBeTrue();
+});
+
+it('promotes an existing user by email', function (): void {
+    $user = User::factory()->create();
+
+    $this->artisan('app:bootstrap-first-admin', [
+        'email' => $user->email,
+    ])->assertExitCode(0);
+
+    expect($user->fresh()->isAn('admin'))->toBeTrue();
+});
+
+it('fails when the user does not exist', function (): void {
+    $this->artisan('app:bootstrap-first-admin', [
+        'email' => 'missing@example.com',
+    ])->assertExitCode(1);
+});