/**
 * Slash command management -- discovery, installation, and syncing.
 *
 * Commands are markdown files in ~/.agents/commands/ exposed as `/command-name`
 * shortcuts by agents. This module discovers them, converts between formats
 * (markdown for Claude/Codex, TOML for Gemini), and installs them into
 * agent version homes.
 */
import type { AgentId, CommandInstallation } from './types.js';
/** Scope of a command: user-global or project-local. */
export type CommandScope = 'user' | 'project';
/** Parsed metadata from a command file's YAML frontmatter. */
export interface CommandMetadata {
    name: string;
    description: string;
    /** When set, sync only to these agents (aliases resolved at parse time). */
    agents?: AgentId[];
    /** Minimum agent CLI version (inclusive) for this command. */
    since?: string;
    /** Exclusive upper bound on agent CLI version for this command. */
    until?: string;
    /** Alternate names this command also resolves under (frontmatter `aliases:`). */
    aliases?: string[];
}
export type CommandApplyFailReason = 'unsupported' | 'agent_excluded' | 'too_old' | 'too_new';
export type CommandApplyResult = {
    ok: true;
} | {
    ok: false;
    reason: CommandApplyFailReason;
    need?: string;
};
/**
 * Whether a slash command should sync to the given agent@version. Checks
 * frontmatter `agents` / `since` / `until` after the agent-level commands
 * (or commands-as-skills) capability gate.
 */
export declare function commandAppliesTo(agent: AgentId, version: string, metadata: Pick<CommandMetadata, 'agents' | 'since' | 'until'> | null | undefined): CommandApplyResult;
export declare function explainCommandSkip(agent: AgentId, version: string, commandName: string, result: CommandApplyResult): string;
/** Result of validating command metadata. */
export interface ValidationResult {
    valid: boolean;
    errors: string[];
    warnings: string[];
}
/** A command discovered in a repository's commands/ directory. */
export interface DiscoveredCommand {
    name: string;
    description: string;
    sourcePath: string;
    isShared: boolean;
    validation: ValidationResult;
}
/** A command installed in an agent's config directory. */
export interface InstalledCommand {
    name: string;
    scope: CommandScope;
    path: string;
    description?: string;
}
/** Parse command metadata (name, description, targeting) from YAML frontmatter or TOML headers. */
export declare function parseCommandMetadata(filePath: string): CommandMetadata | null;
/** Discover all command markdown files in a repository's commands/ directory. */
export declare function discoverCommands(repoPath: string): DiscoveredCommand[];
/** Find the source path for a command in a repository. */
export declare function resolveCommandSource(repoPath: string, commandName: string): string | null;
/** Install a command into an agent's config directory, with optional format conversion. */
export declare function installCommand(sourcePath: string, agentId: AgentId, commandName: string, method?: 'symlink' | 'copy'): CommandInstallation & {
    error?: string;
    warnings?: string[];
};
/**
 * Path to the commands dir of a specific version home (not the active one).
 * Respects per-agent commandsSubdir (e.g. 'prompts' for codex).
 */
export declare function getVersionCommandsDir(agent: AgentId, version: string): string;
/**
 * List command names (without extension) installed in a specific version home.
 */
export declare function listCommandsInVersionHome(agent: AgentId, version: string): string[];
export interface VersionCommandDiff {
    agent: AgentId;
    version: string;
    toAdd: string[];
    toUpdate: string[];
    matched: string[];
    /** Installed but excluded by frontmatter agents/since/until — safe to remove. */
    toRemove: string[];
    orphans: string[];
}
/**
 * Compare a version home's commands against central. Returns the reconciliation diff.
 */
/**
 * Flattened names of plugin-bundled commands (`<plugin>-<command>`), matching
 * exactly how `syncPluginToVersion` installs a plugin's `commands/<cmd>.md` as a
 * command-skill (plugins.ts → `installCommandSkillToVersion(agentDir,
 * `${plugin.name}-${cmd}`, …)`). These are source-managed by their plugin, so
 * the orphan detector must NOT flag them — else `prune cleanup` proposes
 * deleting live plugin commands (swarm-plan, code-review, …). Scans user +
 * system + extra marketplaces (no project layer), matching the trusted sources.
 */
export declare function listPluginCommandNames(): Set<string>;
export declare function diffVersionCommands(agent: AgentId, version: string): VersionCommandDiff;
/**
 * Install a single command from central into a specific version home.
 * Handles markdown-to-TOML conversion when the agent requires it.
 */
export declare function installCommandToVersion(agent: AgentId, version: string, commandName: string, method?: 'symlink' | 'copy'): {
    success: boolean;
    error?: string;
    skipped?: boolean;
    skipReason?: string;
};
/**
 * Remove a single command from a specific version home.
 * Soft-deletes to ~/.agents/.trash/commands/.
 */
export declare function removeCommandFromVersion(agent: AgentId, version: string, commandName: string): {
    success: boolean;
    error?: string;
};
/**
 * Iterate all (agent, version) pairs that support commands and are installed,
 * optionally scoped to a single agent/version.
 */
export declare function iterCommandsCapableVersions(filter?: {
    agent?: AgentId;
    version?: string;
}): Array<{
    agent: AgentId;
    version: string;
}>;
/** Remove a command from an agent's config directory. */
export declare function uninstallCommand(agentId: AgentId, commandName: string): boolean;
/**
 * List installed commands with scope information.
 * Pass options.home to read from a version-managed agent's home directory.
 */
export declare function listInstalledCommandsWithScope(agentId: AgentId, cwd?: string, options?: {
    home?: string;
}): InstalledCommand[];
/**
 * Install a command to central ~/.agents/commands/ directory.
 * Shims will symlink this to per-agent directories for synced agents.
 */
export declare function installCommandCentrally(sourcePath: string, commandName: string): {
    success: boolean;
    path: string;
    error?: string;
    warnings?: string[];
};
/**
 * List commands from user (~/.agents/commands/) and system (~/.agents/.system/commands/) dirs.
 * User dir takes priority; deduplication preserves first occurrence.
 */
export declare function listCentralCommands(): string[];
/**
 * Get detailed info about a command from central storage.
 */
export declare function getCommandInfo(name: string): {
    name: string;
    description: string;
    path: string;
    content: string;
} | null;
