@stoneforge/quarry 1.12.0 → 1.13.0

package/dist/external-sync/sync-engine.d.ts

@@ -0,0 +1,298 @@
+/**
+ * Sync Engine — orchestrates push/pull operations between Stoneforge and external services
+ *
+ * The sync engine coordinates bidirectional synchronization between Stoneforge elements
+ * and external services (GitHub, Linear, etc.) using the provider registry and adapters.
+ *
+ * Core operations:
+ * - push(): Push locally-changed linked elements to external services
+ * - pull(): Pull externally-changed items into Stoneforge
+ * - sync(): Bidirectional sync (push then pull)
+ *
+ * Change detection:
+ * - Push: Query events since lastPushedAt, filter to elements with _externalSync metadata,
+ *   compare content hash against lastPushedHash
+ * - Pull: Call adapter.listIssuesSince() using global sync cursor from settings,
+ *   compare against lastPulledHash
+ *
+ * Usage:
+ * ```typescript
+ * import { createSyncEngine } from '@stoneforge/quarry';
+ *
+ * const engine = createSyncEngine({ api, registry, settings });
+ * const result = await engine.push({ all: true });
+ * const result = await engine.pull();
+ * const result = await engine.sync({ dryRun: true });
+ * ```
+ */
+import type { ExternalSyncResult, ExternalTask, ConflictStrategy, ProviderConfig } from '@stoneforge/core';
+import type { Element, ElementId, Timestamp, EventFilter } from '@stoneforge/core';
+import type { ProviderRegistry } from './provider-registry.js';
+/**
+ * Options for sync operations (push, pull, sync)
+ */
+export interface SyncOptions {
+    /** Report what would change without making changes */
+    readonly dryRun?: boolean;
+    /** Sync specific tasks only (by element ID) */
+    readonly taskIds?: readonly string[];
+    /** Sync all linked tasks */
+    readonly all?: boolean;
+    /** Force push all linked tasks, skipping hash comparison and event query guards */
+    readonly force?: boolean;
+}
+/**
+ * Minimal QuarryAPI interface — only the methods the sync engine needs.
+ * Avoids coupling to the full QuarryAPI type.
+ */
+export interface SyncEngineAPI {
+    /** Get a single element by ID */
+    get<T extends Element>(id: ElementId): Promise<T | null>;
+    /** List elements matching a filter */
+    list<T extends Element>(filter?: Record<string, unknown>): Promise<T[]>;
+    /** Update an element */
+    update<T extends Element>(id: ElementId, updates: Partial<T>): Promise<T>;
+    /** Create a new element */
+    create<T extends Element>(input: Record<string, unknown>): Promise<T>;
+    /** List events matching a filter */
+    listEvents(filter?: EventFilter): Promise<Array<{
+        elementId: ElementId;
+        eventType: string;
+        createdAt: Timestamp;
+    }>>;
+}
+/**
+ * Minimal settings interface for sync cursor storage.
+ * Uses the generic getSetting/setSetting pattern.
+ */
+export interface SyncEngineSettings {
+    /** Get a setting value by key */
+    getSetting(key: string): {
+        value: unknown;
+    } | undefined;
+    /** Set a setting value by key */
+    setSetting(key: string, value: unknown): {
+        value: unknown;
+    };
+}
+/**
+ * Conflict resolver interface — resolves conflicts when both local and remote changed.
+ * The actual implementation is in conflict-resolver.ts (separate task).
+ * The sync engine uses this interface to decouple from the resolver implementation.
+ */
+export interface SyncConflictResolver {
+    /**
+     * Resolve a conflict between local and remote versions.
+     *
+     * @param localElement - The local Stoneforge element
+     * @param remoteItem - The external task/item
+     * @param strategy - The conflict strategy to apply
+     * @returns Resolution result indicating which side wins, or 'manual' for unresolved
+     */
+    resolve(localElement: Element, remoteItem: ExternalTask, strategy: ConflictStrategy): ConflictResolution;
+}
+/**
+ * Result of conflict resolution
+ */
+export interface ConflictResolution {
+    /** Which side won ('local', 'remote', or 'manual' for unresolved) */
+    readonly winner: 'local' | 'remote' | 'manual';
+    /** Whether the conflict was auto-resolved */
+    readonly resolved: boolean;
+}
+/**
+ * Configuration for the sync engine
+ */
+export interface SyncEngineConfig {
+    /** QuarryAPI instance for element CRUD + events */
+    readonly api: SyncEngineAPI;
+    /** Provider registry for looking up providers and adapters */
+    readonly registry: ProviderRegistry;
+    /** Settings service for sync cursor storage */
+    readonly settings?: SyncEngineSettings;
+    /** Conflict resolver (optional — defaults to last-write-wins) */
+    readonly conflictResolver?: SyncConflictResolver;
+    /** Default conflict strategy */
+    readonly defaultConflictStrategy?: ConflictStrategy;
+    /** Default provider config (for pull — specifies which provider/project to sync) */
+    readonly providerConfigs?: readonly ProviderConfig[];
+}
+/**
+ * Sync Engine — coordinates push/pull operations between Stoneforge and external services.
+ *
+ * The engine is stateless — all state is stored in element metadata (_externalSync)
+ * and settings (sync cursors). Each operation reads current state, computes changes,
+ * and writes updated state.
+ */
+export declare class SyncEngine {
+    private readonly api;
+    private readonly registry;
+    private readonly settings;
+    private readonly conflictResolver;
+    private readonly defaultStrategy;
+    private readonly providerConfigs;
+    constructor(config: SyncEngineConfig);
+    /**
+     * Push locally-changed linked elements to external services.
+     *
+     * Algorithm:
+     * 1. Find elements with _externalSync metadata
+     * 2. For each element, query events since lastPushedAt
+     * 3. Compare current content hash against lastPushedHash
+     * 4. If hash differs, push changes to external service via adapter
+     * 5. Update _externalSync metadata with new timestamp and hash
+     *
+     * @param options - Push options (dryRun, taskIds, all)
+     * @returns Aggregated sync result across all providers
+     */
+    push(options?: SyncOptions): Promise<ExternalSyncResult>;
+    /**
+     * Push a single element to its external service.
+     *
+     * @returns 'pushed' if changes were sent, 'skipped' if no changes detected
+     */
+    private pushElement;
+    /**
+     * Pull externally-changed items into Stoneforge.
+     *
+     * Algorithm:
+     * 1. For each configured provider, get the sync cursor (last poll timestamp)
+     * 2. Call adapter.listIssuesSince(project, cursor) to find changed items
+     * 3. For each changed item:
+     *    a. If linked to a local element, compare against lastPulledHash
+     *    b. If unlinked and options.all is set, create a new Stoneforge task
+     *    c. If both local and remote changed, use conflict resolver
+     * 4. Update sync cursors and element metadata
+     *
+     * @param options - Pull options (dryRun, taskIds, all)
+     * @returns Aggregated sync result
+     */
+    pull(options?: SyncOptions): Promise<ExternalSyncResult>;
+    /**
+     * Pull changes from a specific provider.
+     */
+    private pullFromProvider;
+    /**
+     * Pull a single external item into Stoneforge.
+     *
+     * @returns 'pulled' if local element was updated, 'skipped' if no changes,
+     *          'created' if a new task was created
+     */
+    private pullItem;
+    /**
+     * Bidirectional sync — push then pull.
+     *
+     * Runs push first to send local changes, then pull to receive remote changes.
+     * Results are merged from both operations.
+     *
+     * @param options - Sync options (dryRun, taskIds, all)
+     * @returns Merged sync result
+     */
+    sync(options?: SyncOptions): Promise<ExternalSyncResult>;
+    /**
+     * Find elements that are linked to external services and match the given options.
+     *
+     * - If taskIds is specified, returns only those tasks (that have _externalSync)
+     * - If all is true, returns all tasks with _externalSync metadata
+     * - Otherwise, returns tasks with _externalSync that have been updated
+     */
+    private findLinkedElements;
+    /**
+     * Find elements linked to a specific provider and project.
+     */
+    private findLinkedElementsForProvider;
+    /**
+     * Convert an ExternalTask to partial updates for applying to a local element.
+     *
+     * Delegates to externalTaskToTaskUpdates() from task-sync-adapter.ts, which
+     * uses the provider's TaskSyncFieldMapConfig for correct status, priority,
+     * taskType, and tag mapping. The provider is looked up from item.provider.
+     *
+     * @param item - The external task to convert
+     * @param existingTask - The existing local task (for diff mode), or undefined
+     * @returns Partial<Task> with the mapped fields
+     */
+    private externalItemToUpdates;
+    /**
+     * Create a new Stoneforge task from an unlinked external item.
+     */
+    private createTaskFromExternal;
+    /**
+     * Sync the description (body) from an external item to the local task's
+     * description document.
+     *
+     * - If the task already has a descriptionRef, compare the body against the
+     *   existing document content and update only if changed.
+     * - If the task has no descriptionRef and the body is non-empty, create a
+     *   new document and return the descriptionRef to link.
+     * - If the body is empty/undefined, skip (don't delete existing descriptions).
+     *
+     * @returns Partial update with descriptionRef if a new document was created,
+     *          or empty object if no descriptionRef change is needed.
+     */
+    private syncDescriptionFromExternal;
+    /**
+     * Create a new description document for a task.
+     *
+     * Uses the same pattern as the server-side task creation:
+     * - contentType: 'markdown'
+     * - category: 'task-description' tag
+     * - createdBy: 'system'
+     *
+     * @param body - The description content
+     * @param taskTitle - The task title (used in the document title)
+     * @returns The DocumentId of the created document
+     */
+    private createDescriptionDocument;
+    /**
+     * Get the sync cursor for a provider+project+adapterType.
+     * Returns a timestamp indicating the last time we polled this combination.
+     */
+    private getSyncCursor;
+    /**
+     * Update the sync cursor for a provider+project+adapterType.
+     */
+    private setSyncCursor;
+    /**
+     * Get a TaskSyncAdapter for a given provider name.
+     */
+    private getTaskAdapter;
+    /**
+     * Get the ProviderConfig for a given provider name.
+     */
+    private getProviderConfig;
+    /**
+     * Get the primary provider name (for result reporting).
+     */
+    private getPrimaryProvider;
+    /**
+     * Get the primary project (for result reporting).
+     */
+    private getPrimaryProject;
+}
+/**
+ * Create a new SyncEngine instance.
+ *
+ * @param config - Sync engine configuration
+ * @returns A new SyncEngine instance
+ *
+ * @example
+ * ```typescript
+ * const engine = createSyncEngine({
+ *   api: quarryApi,
+ *   registry: providerRegistry,
+ *   settings: settingsService,
+ * });
+ *
+ * // Push locally-changed tasks
+ * const pushResult = await engine.push({ all: true });
+ *
+ * // Pull externally-changed items
+ * const pullResult = await engine.pull();
+ *
+ * // Bidirectional sync
+ * const syncResult = await engine.sync({ dryRun: true });
+ * ```
+ */
+export declare function createSyncEngine(config: SyncEngineConfig): SyncEngine;
+//# sourceMappingURL=sync-engine.d.ts.map

package/dist/external-sync/sync-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-engine.d.ts","sourceRoot":"","sources":["../../src/external-sync/sync-engine.ts"],"names":[],"mappings":"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"}