<?php

declare(strict_types=1);

namespace PpPhp\Core\Deploy;

/**
 * A remote file transport (FTP, FTPS or SFTP).
 *
 * Implementations wrap a single live-server connection and expose the
 * primitives the DeployManager and the file browser need to mirror a local
 * output directory onto the server and let the user manage remote files.
 */
interface TransportInterface
{
    /** Open and authenticate the connection. Throws TransportException on failure. */
    public function connect(): void;

    /**
     * Run a step-by-step connection probe WITHOUT throwing, returning a verbose
     * report so the UI can tell the user exactly where it failed.
     *
     * @return array{
     *   ok:bool,
     *   summary:string,
     *   stages:list<array{stage:string,ok:bool,detail:string}>
     * }
     */
    public function diagnose(): array;

    /**
     * Ensure a remote directory (and all of its parents) exists.
     * Safe to call repeatedly; implementations should memoise.
     */
    public function ensureDir(string $remoteDir): void;

    /** Upload a single local file to the given absolute remote path. */
    public function put(string $localPath, string $remotePath): bool;

    /**
     * List a remote directory.
     *
     * @return list<array{name:string,type:string,size:int,mtime:?int}>
     *         type is 'dir', 'file' or 'link'.
     */
    public function listDir(string $remoteDir): array;

    /** Create a single remote directory (parents are the caller's job). */
    public function makeDir(string $remoteDir): bool;

    /** Rename/move a remote entry. */
    public function rename(string $from, string $to): bool;

    /** Delete a remote directory (must be empty unless the impl recurses). */
    public function removeDir(string $remoteDir): bool;

    /**
     * Return ['size' => int, 'mtime' => int|null] for a remote file,
     * or null when the file does not exist.
     *
     * @return array{size:int,mtime:?int}|null
     */
    public function stat(string $remotePath): ?array;

    /** Delete a remote file. Returns false when the file was absent or protected. */
    public function delete(string $remotePath): bool;

    /** Close the connection. Safe to call more than once. */
    public function close(): void;

    /** The wire protocol in use: 'ftp', 'ftps' or 'sftp'. */
    public function protocol(): string;
}
