export interface CheckUpdateOptions {
    forgeRoot: string;
    configPath: string;
    cwd?: string;
    homeDir?: string;
}
export interface ProjectCache {
    migratedFrom?: string;
    localVersion?: string;
    distribution?: string;
    forgeRoot?: string;
    forgeRef?: string;
    updateStatus?: "pending" | "complete";
    pendingReason?: string | null;
    pendingMigrations?: string[];
}
export interface InstallRecord {
    path: string;
    version: string;
    distribution: string;
    scope: "user" | "project" | "unknown";
    enabled: boolean;
}
/**
 * Derives the distribution name from a plugin root path.
 * Ported verbatim from forge/forge/hooks/check-update.js `detectDistribution()`.
 *
 * Returns "forge@skillforge" for skillforge-marketplace installs,
 * "forge@forge" for all others (direct forge installs).
 */
export declare function detectDistribution(root: string): string;
/**
 * Reads and parses the project-level update-check cache from .forge/update-check-cache.json.
 * Returns null if the file is absent or malformed.
 * Non-fatal — all errors are swallowed.
 */
export declare function readProjectCache(forgeDir: string): ProjectCache | null;
/**
 * Builds a Forge-awareness message if this project has a .forge/config.json.
 * Corresponds to the forge-awareness context injection in check-update.js.
 *
 * In the plugin, this is emitted as {"additionalContext":"..."} to stdout.
 * In forge-cli, the caller does ctx.ui.notify(msg, "info") — pi has no
 * session_start additionalContext protocol.
 *
 * Returns null when configPath is missing or unreadable (e.g. outside-Forge project).
 */
export declare function buildForgeAwarenessMsg(configPath: string): string | null;
/**
 * Scans known plugin locations for all Forge installations.
 * Ported from check-update.js scanPluginInstallations() with injectable options for testing.
 *
 * Returns an array of installation records with version, distribution, scope, enabled status.
 */
export declare function scanPluginInstallations(opts?: {
    homeDir?: string;
    cwd?: string;
}): InstallRecord[];
/**
 * Builds a multi-plugin awareness message if multiple Forge installations are detected.
 * Returns null if only one (or zero) installations found.
 */
export declare function buildMultiPluginMsg(opts: CheckUpdateOptions): string | null;
/**
 * Syncs paths.forgeRoot and paths.forgeRef in .forge/config.json if they drift.
 * Detects distribution switches (forge@forge ↔ forge@skillforge) and returns a
 * notification message if the distribution changed; returns null otherwise.
 *
 * Also updates the project-level cache (.forge/update-check-cache.json) with
 * current distribution, forgeRoot, and forgeRef (preserving updateStatus, pendingMigrations).
 *
 * Corresponds to the "Distribution + forgeRoot/forgeRef sync" section in check-update.js.
 */
export declare function syncForgeRootAndRef(opts: CheckUpdateOptions): string | null;
/**
 * Surfaces a pending-migration warning if the project cache shows updateStatus === "pending".
 * Returns the warning message string, or null if no pending state or cache absent.
 *
 * Corresponds to FR-002 pending-state surfacing in check-update.js.
 */
export declare function buildPendingMigrationMsg(configPath: string): string | null;
/**
 * Detect binary-project version drift: the bundled plugin version is newer
 * than the project's last-migrated version, meaning `/forge:update` has
 * pending migrations that haven't been applied yet.
 *
 * Returns a notification string if drift is detected, null otherwise.
 */
export declare function buildVersionDriftMsg(configPath: string, bundledVersion: string): string | null;