/**
 * @fileoverview Declarative dry-run preview builder.
 *
 * Why a builder instead of returning an object: dry-run implementations vary
 * significantly — some commands need to show a request body, others only need
 * a description. A fluent builder lets command authors write:
 *
 *   return dryRun("POST", url).body({ name }).description("Create item").build();
 *
 * instead of manually constructing `{ method, url, body, description }` with
 * optional fields. The `build()` call also creates an immutable snapshot, so
 * accidental mutations after returning from `dryRun()` don't affect the result.
 *
 * Why `build()` returns a copy: `DryRunResult` is passed through the framework's
 * `formatOutput` pipeline. If the same builder object were reused across calls,
 * mutating it would corrupt earlier results. Returning a shallow copy is cheap
 * and guarantees isolation.
 *
 * Design decision: `body()` and `description()` are optional. Commands that
 * can't determine a body or description before execution simply omit these calls.
 * The framework's `formatOutput` handles undefined fields gracefully.
 */
import type { DryRunResult } from "../framework/types.js";
/**
 * A fluent builder for constructing a dry-run preview.
 *
 * @example
 * ```ts
 * return dryRun("POST", `/api/data/${code}/create`)
 *   .body({ name: "test", amount: 100 })
 *   .description("Create a new record in dataset")
 *   .build();
 * ```
 */
export interface DryRunBuilder {
    /**
     * Attaches the HTTP request body that would be sent.
     * @param data - Request payload (object or array).
     */
    body(data: Record<string, any> | unknown[]): DryRunBuilder;
    /**
     * Attaches a human-readable description of what the operation will do.
     * This is shown in the `pretty` output format.
     * @param desc - Description string.
     */
    description(desc: string): DryRunBuilder;
    /**
     * Freezes the builder state into an immutable `DryRunResult`.
     * Subsequent calls to `body()` or `description()` do not affect the returned object.
     */
    build(): DryRunResult;
}
/**
 * Creates a new dry-run preview builder.
 *
 * @param method - HTTP method (e.g. `"POST"`, `"DELETE"`).
 * @param url    - Full URL that would be requested.
 *
 * @example
 * ```ts
 * const result = dryRun("POST", "https://api.example.com/items").build();
 * ```
 */
export declare function dryRun(method: string, url: string): DryRunBuilder;