/**
 * Canonical scai output envelope.
 *
 * Every CLI command emits this shape under `--json` (with optional keys
 * absent when N/A). Agents and downstream automation branch on `data`
 * regardless of which surface produced the output; the rest of the
 * keys carry structured metadata (counts, pagination, plan-only flag,
 * baseline ignore count, etc.) in canonical slots.
 *
 *   {
 *     "command": "deploy.environments.list",
 *     "environment": "demo",
 *     "data": <T>,            // primary result (object, array, scalar, or null)
 *     "count"?: number,       // present when data is an array
 *     "totalCount"?: number,  // present when paginated and known
 *     "pageSize"?: number,    // present when paginated
 *     "whatIf"?: true,        // present iff plan-only
 *     "ignoredCount"?: number,// present when baseline filtering applied
 *     "summary"?: string,     // human-readable headline
 *     "meta"?: Record<string, unknown>  // command-specific extras
 *   }
 *
 * Prior to 2026-05-14, three different keys held the same slot:
 * `result` (deploy commands), `results` (hygiene audit/cleanup), and
 * `request` (deploy what-if). Agents parsing scai output had to branch
 * on shape per-command. The unification renames all three to `data`.
 *
 * The module lives in `src/shared/` so any task surface (deploy,
 * hygiene, serialization, recipe, workflow, webhook) can import it
 * without crossing layer boundaries.
 */
export interface ScaiEnvelope<T = unknown> {
    command: string;
    environment: string | null;
    data: T;
    count?: number;
    totalCount?: number;
    pageSize?: number;
    whatIf?: true;
    ignoredCount?: number;
    summary?: string;
    meta?: Record<string, unknown>;
}
/**
 * Build a `ScaiEnvelope` from a primary `data` value plus an `extra`
 * bag. Keys in `extra` that match canonical envelope fields are
 * hoisted to envelope-level; everything else collects under `meta`.
 * Auto-computes `count` when `data` is an array (overridable via
 * `extra.count`).
 */
export declare const buildScaiEnvelope: <T>(params: {
    command: string;
    environment: string | null | undefined;
    data: T;
    extra?: Record<string, unknown>;
}) => ScaiEnvelope<T>;
/**
 * Read the entire stdin to a string, then parse a `ScaiEnvelope`.
 * Used by cleanup commands that accept `--from-stdin` to consume an
 * audit's `--json` output directly, skipping their internal re-run of
 * the audit. The contract: callers expect a single JSON object that
 * matches the canonical envelope. Extra keys are tolerated;
 * `command`, `data` are required.
 *
 * Returns the parsed envelope cast to the expected `data` shape (no
 * structural validation beyond key presence — the cleanup task layer
 * runs its own zod validation on the items in `data`).
 */
export declare const readScaiEnvelopeFromStdin: <T = unknown>() => Promise<ScaiEnvelope<T>>;