<?php

declare(strict_types=1);

namespace Sarcio\WordPress\Assistant;

use Closure;

/**
 * One thing the assistant can do on this site. The plugin ships every one of
 * them; Sarcio only ever asks for one by name with arguments that must fit
 * its schema. A write names what it changed (`before`/`after`) so the journal
 * can undo it, and previews the change in plain words before it is applied.
 * A write that can be shown on the site without being made carries `stage`:
 * given the arguments and the preview's overlay, it reads through the
 * overlay, records its effect on it and answers the same before/after text.
 */
final class Ability
{
    public const READ = 'read';
    public const WRITE = 'write';

    /**
     * @param array<string,mixed> $input JSON schema for the arguments
     * @param Closure(array<string,mixed>):bool $permission
     * @param Closure(array<string,mixed>):array<string,mixed> $run
     * @param Closure(array<string,mixed>):array{summary:string,before:string,after:string,plugin?:array<string,mixed>}|null $preview
     * @param Closure(array<string,mixed>,array<string,mixed>):array<string,mixed>|null $undo given the journal's before and after
     * @param Closure(array<string,mixed>,Overlay):array{summary:string,before:string,after:string}|null $stage
     */
    public function __construct(
        public readonly string $name,
        public readonly string $label,
        public readonly string $kind,
        public readonly string $description,
        public readonly array $input,
        public readonly Closure $permission,
        public readonly Closure $run,
        public readonly ?Closure $preview = null,
        public readonly ?Closure $undo = null,
        public readonly bool $consent = false,
        public readonly ?Closure $stage = null,
    ) {
    }

    /** @param array<string,mixed> $args */
    public function allowed(array $args): bool
    {
        return ($this->permission)($args);
    }

    /** @param array<string,mixed> $args */
    public function validate(array $args): ?string
    {
        return Schema::check($this->input, $args);
    }

    /** What Sarcio is told about this ability. */
    public function describe(): array
    {
        return [
            'description' => $this->description,
            'input' => $this->input,
            'kind' => $this->kind,
            'name' => $this->name,
        ];
    }
}