/**
 * Task Sync Adapter Utilities
 *
 * Shared field mapping logic for converting between Stoneforge tasks and
 * external task representations (e.g., GitHub Issues, Linear issues).
 *
 * These utilities are provider-agnostic — each provider supplies its own
 * TaskSyncFieldMapConfig that tells the adapter how to map statuses,
 * priorities, task types, and labels to/from the external system.
 *
 * Key functions:
 * - taskToExternalTask: Convert a Stoneforge Task → ExternalTaskInput for push
 * - externalTaskToTaskUpdates: Convert an ExternalTask → Partial<Task> for pull
 */
import type { Task, TaskStatus, Priority, TaskTypeValue, DocumentId, Element, ElementId } from '@stoneforge/core';
import type { ExternalTask, ExternalTaskInput } from '@stoneforge/core';
/**
 * Minimal API interface used by task sync adapter utilities.
 * Only requires `get()` for description hydration.
 * Both QuarryAPI and SyncEngineAPI satisfy this interface structurally.
 */
export interface TaskSyncAPI {
    get<T extends Element>(id: ElementId): Promise<T | null>;
}
/**
 * Provider-specific configuration for mapping task fields between
 * Stoneforge and an external system.
 *
 * Each provider (GitHub, Linear, etc.) supplies its own config that
 * describes how Stoneforge concepts map to the provider's label/state model.
 */
export interface TaskSyncFieldMapConfig {
    /**
     * Maps Stoneforge priority values to external label strings.
     * e.g., { 1: 'priority:critical', 2: 'priority:high', 3: 'priority:medium', ... }
     */
    readonly priorityLabels: Record<Priority, string>;
    /**
     * Maps Stoneforge task type values to external label strings.
     * e.g., { bug: 'type:bug', feature: 'type:feature', task: 'type:task', chore: 'type:chore' }
     */
    readonly taskTypeLabels: Record<TaskTypeValue, string>;
    /**
     * Optional: Maps Stoneforge TaskStatus values to external label strings.
     * When present, status labels are pushed alongside priority and type labels,
     * providing granular status visibility on external systems that only have
     * binary open/closed states (e.g., GitHub).
     *
     * Optional because some providers (e.g., Linear) map status natively
     * via workflow states and don't need label-based status mapping.
     *
     * e.g., { open: 'status:open', in_progress: 'status:in-progress', ... }
     */
    readonly statusLabels?: Record<string, string>;
    /**
     * Prefix for sync-managed labels in the external system.
     * Labels with this prefix are managed by the sync system and will be
     * added/removed automatically. User labels without this prefix are preserved.
     * e.g., 'sf:' would produce labels like 'sf:priority:critical', 'sf:type:bug'
     */
    readonly syncLabelPrefix: string;
    /**
     * Converts a Stoneforge TaskStatus to the external system's state.
     * Most external systems only have 'open' and 'closed' states.
     * e.g., 'in_progress' → 'open', 'closed' → 'closed'
     */
    readonly statusToState: (status: TaskStatus) => 'open' | 'closed';
    /**
     * Converts an external state + labels back to a Stoneforge TaskStatus.
     * Labels are provided to allow more granular status inference
     * (e.g., external 'open' + label 'status:in-progress' → 'in_progress').
     */
    readonly stateToStatus: (state: 'open' | 'closed', labels: string[]) => TaskStatus;
}
/**
 * Converts a Stoneforge Task into an ExternalTaskInput for creating/updating
 * an issue in an external system.
 *
 * Handles:
 * - Title mapping (1:1)
 * - Status → state mapping via config.statusToState
 * - Tags → labels (user tags preserved, sync-managed labels added)
 * - Priority → label via config.priorityLabels
 * - Task type → label via config.taskTypeLabels
 * - Description hydration from descriptionRef document via api.get()
 *
 * Note: Assignees are intentionally NOT written to external systems.
 * Stoneforge assignees are ephemeral agents (e.g., el-xxxx) that don't
 * correspond to valid users on external platforms like GitHub.
 *
 * @param task - The Stoneforge task to convert
 * @param config - Provider-specific field mapping configuration
 * @param api - API with get() for hydrating description documents
 * @returns ExternalTaskInput ready for the provider adapter
 */
export declare function taskToExternalTask(task: Task, config: TaskSyncFieldMapConfig, api: TaskSyncAPI): Promise<ExternalTaskInput>;
/**
 * Converts an ExternalTask into a partial Task update object for applying
 * external changes to a local Stoneforge task.
 *
 * Handles:
 * - Title mapping (1:1)
 * - State + labels → status mapping via config.stateToStatus
 * - Labels → priority, taskType, tags (separating sync-managed from user labels)
 * - Assignees (first assignee mapped if present)
 *
 * If existingTask is provided, only changed fields are returned (diff mode).
 * If existingTask is undefined, all fields are returned (create mode).
 *
 * Note: Description (body) handling is NOT included in the returned partial.
 * The caller (sync engine) is responsible for creating/updating the description
 * Document and linking via descriptionRef, since that requires document creation
 * which is a separate API operation.
 *
 * @param externalTask - The external task to convert
 * @param existingTask - The existing local task (undefined for new tasks)
 * @param config - Provider-specific field mapping configuration
 * @returns Partial<Task> with only the changed fields (or all fields if no existingTask)
 */
export declare function externalTaskToTaskUpdates(externalTask: ExternalTask, existingTask: Task | undefined, config: TaskSyncFieldMapConfig): Partial<Task>;
/**
 * Builds the complete set of external labels for a task.
 *
 * Combines:
 * 1. Sync-managed priority label (prefixed)
 * 2. Sync-managed task type label (prefixed)
 * 3. Sync-managed status label (prefixed, when config.statusLabels is present)
 * 4. User tags from the task (not prefixed — these are user-owned)
 */
export declare function buildExternalLabels(task: Task, config: TaskSyncFieldMapConfig): string[];
/**
 * Result of parsing external labels into structured task fields
 */
export interface ParsedExternalLabels {
    /** Extracted priority value, or undefined if no priority label found */
    priority: Priority | undefined;
    /** Extracted task type value, or undefined if no task type label found */
    taskType: TaskTypeValue | undefined;
    /** Extracted status value, or undefined if no status label found */
    status: TaskStatus | undefined;
    /** Labels that are not sync-managed (user tags) */
    userTags: string[];
}
/**
 * Parses external labels into structured task field values.
 *
 * Separates sync-managed labels (prefixed) from user labels,
 * and extracts priority, task type, and status values from the managed labels.
 */
export declare function parseExternalLabels(labels: readonly string[], config: TaskSyncFieldMapConfig): ParsedExternalLabels;
/**
 * Hydrates a task's description from its descriptionRef document.
 *
 * If the task has a descriptionRef, fetches the document via the API
 * and returns its content as the body string. Returns undefined if
 * no descriptionRef is set or the document is not found.
 */
export declare function hydrateDescription(descriptionRef: DocumentId | undefined, api: TaskSyncAPI): Promise<string | undefined>;
/**
 * Compares a full update against an existing task and returns only
 * the fields that actually changed.
 *
 * This prevents unnecessary updates when pulling changes from external
 * systems where the data hasn't actually changed.
 */
export declare function diffTaskUpdates(existingTask: Task, fullUpdate: Partial<Task>): Partial<Task>;
/**
 * Returns the TaskSyncFieldMapConfig for a given provider name.
 *
 * Shared utility used by both the CLI link-all command and the sync engine
 * push path to get the correct field mapping for a provider.
 *
 * @param providerName - The provider name (e.g., 'github', 'linear')
 * @returns The provider-specific TaskSyncFieldMapConfig
 */
export declare function getFieldMapConfigForProvider(providerName: string): TaskSyncFieldMapConfig;
//# sourceMappingURL=task-sync-adapter.d.ts.map