/**
 * Command interaction capabilities.
 *
 * Every registered command declares, beside its definition, what it can do
 * without applying, which confirmation it can approve in advance, which
 * interactive-only trust conditions it can meet, how it resolves its inputs,
 * and what persistent state it touches. The declaration is attached through
 * the command annotation mechanism, so the command tree carries it and a
 * static gate can compare every node's declaration with its parsed flags and
 * its executable evidence. Flags that express a capability are built from the
 * narrow builders below, so a command cannot register `--preview` or `--yes`
 * without the declaration that gives the flag its meaning.
 *
 * The declaration states expectations; it is never itself the proof. Purpose
 * fixtures in the executable specifications demonstrate the effects.
 */
import * as ServiceMap from "effect/Context";
import { Command, Flag } from "effect/unstable/cli";
/** The persistent state an applying invocation can change. */
export type CommandEffect = "none" | "workspace" | "authored-source" | "registry" | "credentials" | "installation" | "application-state";
/** How a command obtains the inputs an assessment or apply needs. */
export type CommandInputResolution = "none" | "explicit" | "explicit-or-documented-defaults" | "explicit-or-interactive-selection";
/** An interactive-only trust condition a route can meet while applying. */
export type CommandTrustCondition = "publisher-change";
/** An executable mode a flag switches a command into. */
export interface CommandMode {
    readonly flag: string;
    readonly effect: CommandEffect;
}
export interface CommandCapabilities {
    /** The command assesses its intended change without applying it under `--preview`. */
    readonly preview: boolean;
    /**
     * The one documented confirmation `--yes` approves in advance, or `null`
     * when the command confirms nothing that can be approved in advance.
     */
    readonly preapproval: {
        readonly purpose: string;
    } | null;
    /** Trust conditions the command can meet; each requires interactive approval. */
    readonly trust: ReadonlyArray<CommandTrustCondition>;
    readonly inputs: CommandInputResolution;
    /** The persistent state the default invocation changes when it applies. */
    readonly effect: CommandEffect;
    /** Flags that switch the default invocation into a different effect. */
    readonly modes?: ReadonlyArray<CommandMode>;
}
/**
 * The annotation every registered command carries. Reading a command with no
 * declaration yields `undefined`, which the architecture gate treats as an
 * unclassified route.
 */
export declare const CommandCapabilitiesAnnotation: ServiceMap.Reference<CommandCapabilities | undefined>;
export declare const withCommandCapabilities: (capabilities: CommandCapabilities) => <Name extends string, Input, ContextInput, E, R>(self: Command.Command<Name, Input, ContextInput, E, R>) => Command.Command<Name, Input, ContextInput, E, R>;
export declare const readCommandCapabilities: (command: Command.Command.Any) => CommandCapabilities | undefined;
/** A node that only groups subcommands and executes nothing itself. */
export declare const groupCapabilities: CommandCapabilities;
/** A command that reports or queries and changes no persistent state. */
export declare const readOnlyCapabilities: (inputs?: CommandInputResolution) => CommandCapabilities;
/** A command that changes state directly without an assessment mode. */
export declare const directWriteCapabilities: (effect: Exclude<CommandEffect, "none">, options?: {
    readonly inputs?: CommandInputResolution;
    readonly modes?: ReadonlyArray<CommandMode>;
}) => CommandCapabilities;
/** A command that assesses under `--preview` and confirms nothing in advance. */
export declare const previewableCapabilities: (effect: Exclude<CommandEffect, "none">, options?: {
    readonly inputs?: CommandInputResolution;
    readonly trust?: ReadonlyArray<CommandTrustCondition>;
}) => CommandCapabilities;
/**
 * The assessment flag for a command whose capabilities declare preview. The
 * description may be specialized; the spelling is fixed.
 */
export declare const previewCapabilityFlag: (description?: string) => Flag.Flag<boolean>;
/**
 * The preapproval flag for a command whose capabilities declare a
 * preapprovable confirmation. Its description names that confirmation, so
 * help states the purpose the flag serves on this command.
 */
export declare const preapprovalCapabilityFlag: (capabilities: {
    readonly preapproval: {
        readonly purpose: string;
    };
}) => Flag.Flag<boolean>;
export interface RegisteredCommandCapabilities {
    readonly path: ReadonlyArray<string>;
    readonly command: Command.Command.Any;
    readonly capabilities: CommandCapabilities | undefined;
}
/** Every registered command with its declaration, walked from the given root. */
export declare const registeredCommandCapabilities: (command: Command.Command.Any, path?: ReadonlyArray<string>) => ReadonlyArray<RegisteredCommandCapabilities>;
//# sourceMappingURL=command-capabilities.d.ts.map