/**
 * Shared utilities for command implementations.
 *
 * Small helpers used across multiple commands: prompt cancellation detection,
 * table formatting, spinner management, and platform-specific workarounds.
 */
import type { Command } from 'commander';
import type { AgentId } from '../lib/types.js';
import { type InstalledAgentTargetResult, type VersionSelectionResult } from '../lib/installations/versions.js';
/**
 * Resolve a read/list command's `@version` filter through the agent-spec engine,
 * exiting cleanly on a bad spec. Drop-in for the old
 * `resolveVersionAlias(agent, parts[1])`:
 *   undefined → show all · @default/@pinned → the default version ·
 *   @latest/@oldest/@x.y.z → concrete.
 */
export declare function resolveListFilterOrExit(agent: AgentId, qualifier: string | undefined | null): string | undefined;
import { isPromptCancelled, isInteractiveTerminal, parseCommaSeparatedList } from '../lib/format.js';
export { isPromptCancelled, isInteractiveTerminal, parseCommaSeparatedList };
/** The resolved I/O surface for one command invocation — the human/agent split. */
export interface Surface {
    /** Machine-readable output was requested (`--json`). */
    json: boolean;
    /** Skip confirmation prompts — explicit `--yes`/`-y`, or a non-interactive shell. */
    assumeYes: boolean;
    /** Suppress non-essential human chrome (`--quiet`). */
    quiet: boolean;
    /**
     * Safe to show an interactive picker/prompt: a real terminal AND not asking for
     * `--json` (a JSON consumer is a machine and never wants a picker).
     */
    interactive: boolean;
}
/**
 * Compute a command's I/O surface once, in one place, instead of each command
 * re-deriving the human-vs-agent split (and raw-sniffing `process.std*.isTTY`
 * with inconsistent stream choices — the audit's R4). Reads the merged option
 * set via `optsWithGlobals()`, so it sees the command's own flags and any
 * inherited global ones, and folds in the terminal state:
 *
 *   - `assumeYes` = explicit `--yes` OR a non-interactive shell (no one to prompt).
 *   - `interactive` = a real TTY AND not `--json`.
 *
 * Adopt incrementally: a command switches its ad-hoc `isTTY`/`options.yes` checks
 * to a single `const s = resolveSurface(cmd)` without changing its flag surface.
 */
export declare function resolveSurface(cmd: Command): Surface;
/**
 * Exit with a clean message when a picker would be required in a non-interactive shell.
 */
export declare function requireInteractiveSelection(action: string, alternatives: string[]): never;
/**
 * Print a properly-cased "missing argument" error for destructive commands and
 * exit. Destructive commands (remove, disband, disable) deliberately do NOT
 * fall back to an interactive picker — typing the name is the safety check.
 *
 * Lists available items so the user can copy-paste, but never auto-selects.
 */
export declare function requireDestructiveArg(opts: {
    argName: string;
    command: string;
    itemNoun: string;
    available: string[];
    emptyHint?: string;
}): never;
/**
 * Print long content directly in non-interactive shells, use a pager only for real terminals.
 */
export declare function printWithPager(output: string, lineCount: number): void;
/**
 * A target for resource removal: agent + version.
 */
export interface RemovalTarget {
    agent: string;
    version: string;
    label: string;
}
/**
 * Prompt user to select which agent/version targets to remove a resource from.
 * If only one target, returns it without prompting. If multiple, shows checkbox.
 * Returns empty array if user cancels or selects nothing.
 */
export declare function promptRemovalTargets(resourceName: string, targets: RemovalTarget[], options?: {
    skipPrompt?: boolean;
}): Promise<RemovalTarget[]>;
/**
 * Format a path for display, using ~ for home directory
 */
export declare function formatPath(fullPath: string, cwd?: string): string;
/**
 * Make sure every specific `agent@x.y.z` the user typed is installed before
 * the caller resolves targets. Returns true if the caller should continue,
 * false if the user declined the prompt. Exported so non-standard caller
 * shapes (e.g. mcp.ts's manifest-shaped parser) can run the pre-flight
 * without going through resolveAgentVersionTargets first.
 */
export declare function ensureAgentVersionsInstalled(value: string, availableAgents: readonly AgentId[], options?: {
    yes?: boolean;
}): Promise<boolean>;
/**
 * Resolve a `--agents` selector and, if any requested `agent@version` isn't
 * installed yet, prompt to install it (or auto-install with --yes) before
 * delegating to resolveAgentVersionTargets. Returns null when the user
 * declines the install prompt — callers should treat that as a clean cancel.
 */
export declare function resolveAgentTargetsAutoInstalling(value: string, availableAgents: readonly AgentId[], options?: {
    yes?: boolean;
    allVersions?: boolean;
}): Promise<VersionSelectionResult | null>;
/**
 * Same as resolveAgentTargetsAutoInstalling but returns the broader
 * InstalledAgentTargetResult that includes `directAgents` (for paths like
 * `agents install` and `mcp register` that fall through to unmanaged homes
 * when no managed version is installed).
 */
export declare function resolveInstalledAgentTargetsAutoInstalling(value: string, availableAgents: readonly AgentId[], options?: {
    yes?: boolean;
    allVersions?: boolean;
}): Promise<InstalledAgentTargetResult | null>;
export { VersionNotInstalledError } from '../lib/installations/versions.js';
