<?php

declare(strict_types=1);

namespace App\Domain\Sysapi\Contracts;

use App\Domain\Sysapi\Bridges\FakeSysapi;
use App\Domain\Sysapi\Bridges\SudoBashSysapi;
use App\Domain\Sysapi\Exceptions\SysapiActionNotAllowedException;
use App\Domain\Sysapi\Exceptions\SysapiException;
use App\Domain\Sysapi\Exceptions\SysapiTimeoutException;

/**
 * Panel ↔ OS köprüsü kontrat.
 *
 * Phase 1 Epic 3.
 *
 * Tasarım kararı (master plan §5 Sysapi Layer):
 *   sudo + whitelisted bash wrapper scripts (HestiaCP modeli).
 *   /usr/local/onoxsoft/bin/onx-<command> şeklinde script'ler vardır.
 *   Bu interface o script'lerin tek giriş noktası.
 *
 * Phase 3'te multi-server'a evrildiğinde:
 *   Aynı interface implement edilecek, ama RemoteSshSysapi veya
 *   GrpcAgentSysapi şeklinde başka bir bridge yazılacak.
 *   Consumer kod değişmez.
 *
 * @see SudoBashSysapi
 * @see FakeSysapi
 */
interface SysapiBridge
{
    /**
     * Bir sysapi komutunu çalıştır.
     *
     * @param  string  $command  onx-<command> script ismi (örn: "user-add", "vhost-add")
     * @param  array<string, mixed>  $args  Script'e stdin üzerinden JSON olarak verilecek
     * @param  int  $timeoutSeconds  Komutun maksimum çalışma süresi
     *
     * @throws SysapiException
     * @throws SysapiActionNotAllowedException
     * @throws SysapiTimeoutException
     */
    public function run(string $command, array $args = [], int $timeoutSeconds = 60): SysapiResult;

    /**
     * Gerçek OS çağrısı yapılıyor mu?
     * true = production (SudoBashSysapi), false = fake/test
     */
    public function isReal(): bool;

    /**
     * Whitelist'teki tüm komut adlarını döndürür.
     *
     * @return array<string>
     */
    public function allowedActions(): array;
}
