@stoneforge/quarry 1.13.0 → 1.14.0

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

@@ -25,8 +25,8 @@
  * 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 { ExternalSyncResult, ExternalTask, ExternalDocument, ConflictStrategy, SyncAdapterType, ProviderConfig } from '@stoneforge/core';
+import type { Element, ElementId, Timestamp, EventFilter, Dependency, DependencyType } from '@stoneforge/core';
 import type { ProviderRegistry } from './provider-registry.js';
 /**
  * Options for sync operations (push, pull, sync)
@@ -40,6 +40,28 @@ export interface SyncOptions {
     readonly all?: boolean;
     /** Force push all linked tasks, skipping hash comparison and event query guards */
     readonly force?: boolean;
+    /**
+     * Filter sync operations to specific adapter types.
+     * When set, only elements matching these adapter types will be processed.
+     * When omitted or empty, all adapter types are processed (tasks + documents).
+     */
+    readonly adapterTypes?: readonly SyncAdapterType[];
+    /**
+     * Include documents that are not in any library.
+     * By default, documents without a library parent are excluded from push.
+     * Set to true to include them.
+     */
+    readonly includeNoLibrary?: boolean;
+    /**
+     * Callback invoked with the total element count before processing begins.
+     * Useful for showing progress information or warnings about large sets.
+     */
+    readonly onBeforeProcess?: (count: number) => void;
+    /**
+     * Optional progress callback invoked after each batch completes during push.
+     * Receives the current count of processed elements and the total count.
+     */
+    readonly onProgress?: (current: number, total: number) => void;
 }
 /**
  * Minimal QuarryAPI interface — only the methods the sync engine needs.
@@ -60,6 +82,8 @@ export interface SyncEngineAPI {
         eventType: string;
         createdAt: Timestamp;
     }>>;
+    /** Get all dependencies for an element, optionally filtered by type */
+    getDependencies(id: ElementId, types?: DependencyType[]): Promise<Dependency[]>;
 }
 /**
  * Minimal settings interface for sync cursor storage.
@@ -85,11 +109,11 @@ export interface SyncConflictResolver {
      * Resolve a conflict between local and remote versions.
      *
      * @param localElement - The local Stoneforge element
-     * @param remoteItem - The external task/item
+     * @param remoteItem - The external task/document/item (must have updatedAt)
      * @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;
+    resolve(localElement: Element, remoteItem: ExternalTask | ExternalDocument, strategy: ConflictStrategy): ConflictResolution;
 }
 /**
  * Result of conflict resolution
@@ -117,6 +141,8 @@ export interface SyncEngineConfig {
     /** Default provider config (for pull — specifies which provider/project to sync) */
     readonly providerConfigs?: readonly ProviderConfig[];
 }
+/** Number of documents to push concurrently (balances throughput vs API rate limits) */
+declare const PUSH_CONCURRENCY = 3;
 /**
  * Sync Engine — coordinates push/pull operations between Stoneforge and external services.
  *
@@ -146,12 +172,30 @@ export declare class SyncEngine {
      * @returns Aggregated sync result across all providers
      */
     push(options?: SyncOptions): Promise<ExternalSyncResult>;
+    /**
+     * Process a single element for push — validates sync state, checks skip conditions,
+     * and routes to the appropriate push method (pushElement or pushDocument).
+     *
+     * Extracted from the push() loop body to enable concurrent execution via Promise.allSettled.
+     *
+     * @returns 'pushed' if changes were sent, 'skipped' if element was skipped
+     */
+    private pushSingleElement;
     /**
      * Push a single element to its external service.
      *
      * @returns 'pushed' if changes were sent, 'skipped' if no changes detected
      */
     private pushElement;
+    /**
+     * Push a single document to its external service.
+     *
+     * Parallel to pushElement(), but uses document-specific conversion
+     * (documentToExternalDocumentInput) and the DocumentSyncAdapter.
+     *
+     * @returns 'pushed' if changes were sent, 'skipped' if no changes detected
+     */
+    private pushDocument;
     /**
      * Pull externally-changed items into Stoneforge.
      *
@@ -179,6 +223,23 @@ export declare class SyncEngine {
      *          'created' if a new task was created
      */
     private pullItem;
+    /**
+     * Pull document changes from a specific provider.
+     * Parallel to pullFromProvider(), but uses the DocumentSyncAdapter.
+     */
+    private pullDocumentsFromProvider;
+    /**
+     * Pull a single external document into Stoneforge.
+     * Parallel to pullItem(), but uses document-specific conversion.
+     *
+     * @returns 'pulled' if local element was updated, 'skipped' if no changes,
+     *          'created' if a new document was created
+     */
+    private pullDocumentItem;
+    /**
+     * Create a new Stoneforge document from an unlinked external document.
+     */
+    private createDocumentFromExternal;
     /**
      * Bidirectional sync — push then pull.
      *
@@ -257,6 +318,10 @@ export declare class SyncEngine {
      * Get a TaskSyncAdapter for a given provider name.
      */
     private getTaskAdapter;
+    /**
+     * Get a DocumentSyncAdapter for a given provider name.
+     */
+    private getDocumentAdapter;
     /**
      * Get the ProviderConfig for a given provider name.
      */
@@ -295,4 +360,5 @@ export declare class SyncEngine {
  * ```
  */
 export declare function createSyncEngine(config: SyncEngineConfig): SyncEngine;
+export { PUSH_CONCURRENCY };
 //# sourceMappingURL=sync-engine.d.ts.map

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

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