@stoneforge/quarry 1.12.0 → 1.14.0

package/dist/external-sync/adapters/document-sync-adapter.js

@@ -0,0 +1,325 @@
+/**
+ * Document Sync Adapter Utilities
+ *
+ * Shared field mapping logic for converting between Stoneforge documents and
+ * external document representations (e.g., Notion pages, Obsidian notes).
+ *
+ * These utilities are provider-agnostic — they handle the common conversion
+ * logic that all document sync providers need.
+ *
+ * Key functions:
+ * - documentToExternalDocumentInput: Convert a Stoneforge Document → ExternalDocumentInput for push
+ * - externalDocumentToDocumentUpdates: Convert an ExternalDocument → Partial<Document> for pull
+ * - diffDocumentUpdates: Return only changed fields between existing and updated document
+ * - computeExternalDocumentHash: Deterministic hash for change detection
+ */
+import { createHash } from 'crypto';
+// ============================================================================
+// System Categories
+// ============================================================================
+/**
+ * Document categories that are system-managed and should be excluded from
+ * external sync. These documents are structural (task descriptions, message
+ * content) and are synced through their parent element's sync adapter.
+ */
+export const SYSTEM_CATEGORIES = new Set([
+    'task-description',
+    'message-content',
+]);
+/**
+ * Checks whether a document category is a system category that should
+ * be excluded from document sync.
+ */
+export function isSystemCategory(category) {
+    return SYSTEM_CATEGORIES.has(category);
+}
+/**
+ * Checks whether a document should be included in external sync operations
+ * (link-all, push, pull). A document is syncable if:
+ * - It does not have a system category (task-description, message-content)
+ * - It has a non-empty title (null, undefined, or whitespace-only titles are excluded)
+ *
+ * Documents without titles are typically system-generated (messages, task descriptions)
+ * that happen to not have the system category set, or scratch documents. They all
+ * slugify to "untitled.md" and overwrite each other, so they must be excluded.
+ */
+export function isSyncableDocument(doc) {
+    if (isSystemCategory(doc.category))
+        return false;
+    if (!doc.title || doc.title.trim().length === 0)
+        return false;
+    return true;
+}
+// ============================================================================
+// Content Type Mapping
+// ============================================================================
+/**
+ * Maps Stoneforge ContentType to external document content type.
+ *
+ * Stoneforge uses 'markdown', 'text', and 'json'.
+ * External systems use 'markdown', 'text', and 'html'.
+ * JSON content is mapped to 'text' for external systems since most
+ * document providers don't have a native JSON content type.
+ */
+export function mapContentTypeToExternal(contentType) {
+    switch (contentType) {
+        case 'markdown':
+            return 'markdown';
+        case 'text':
+            return 'text';
+        case 'json':
+            // JSON doesn't have a direct external equivalent; map to text
+            return 'text';
+        default:
+            return 'text';
+    }
+}
+/**
+ * Maps external document content type to Stoneforge ContentType.
+ *
+ * External systems use 'markdown', 'text', and 'html'.
+ * HTML content is mapped to 'text' since Stoneforge doesn't have an HTML
+ * content type — the content is stored as-is, just categorized as text.
+ */
+export function mapContentTypeFromExternal(contentType) {
+    switch (contentType) {
+        case 'markdown':
+            return 'markdown';
+        case 'text':
+            return 'text';
+        case 'html':
+            // HTML doesn't have a direct Stoneforge equivalent; map to text
+            return 'text';
+        default:
+            return 'text';
+    }
+}
+/**
+ * Slugifies a library name for use as a directory name.
+ * Uses the same algorithm as the folder adapter's slugify function:
+ * lowercase, replace non-alphanumeric chars with hyphens, collapse
+ * consecutive hyphens, trim leading/trailing hyphens.
+ *
+ * @param name - Library name to slugify
+ * @returns Slugified directory name
+ */
+function slugifyLibraryName(name) {
+    const slug = name
+        .toLowerCase()
+        .replace(/[^a-z0-9-]/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '');
+    return slug || 'untitled';
+}
+/**
+ * Resolves the library path for a document by querying its parent-child
+ * dependencies. Builds a hierarchical path from the root library down
+ * to the document's immediate parent library.
+ *
+ * For example, if a document belongs to library "API Reference" which
+ * is a child of library "Documentation", the returned path would be
+ * "documentation/api-reference".
+ *
+ * Design decisions:
+ * - If a document belongs to multiple libraries, the first one found is used
+ * - Library names are slugified for directory names
+ * - If the document has no library parent, returns undefined
+ *
+ * @param api - API for querying dependencies and elements
+ * @param documentId - The document's element ID
+ * @returns The slugified library path (e.g., 'documentation/api-reference'), or undefined if not in a library
+ */
+export async function resolveDocumentLibraryPath(api, documentId) {
+    // Find parent-child dependencies where document is the child (blockedId)
+    const deps = await api.getDependencies(documentId, ['parent-child']);
+    if (deps.length === 0) {
+        return undefined;
+    }
+    // Find the first library parent
+    let libraryId;
+    for (const dep of deps) {
+        const parent = await api.get(dep.blockerId);
+        if (parent && parent.type === 'library') {
+            libraryId = dep.blockerId;
+            break;
+        }
+    }
+    if (!libraryId) {
+        return undefined;
+    }
+    // Walk up the library hierarchy to build the full path
+    const pathSegments = [];
+    let currentId = libraryId;
+    const visited = new Set(); // Prevent infinite loops from cycles
+    while (currentId && !visited.has(currentId)) {
+        visited.add(currentId);
+        const library = await api.get(currentId);
+        if (!library || library.type !== 'library') {
+            break;
+        }
+        pathSegments.unshift(slugifyLibraryName(library.name));
+        // Find the parent library of this library
+        const parentDeps = await api.getDependencies(currentId, ['parent-child']);
+        let foundParentLibrary = false;
+        for (const dep of parentDeps) {
+            const parent = await api.get(dep.blockerId);
+            if (parent && parent.type === 'library') {
+                currentId = dep.blockerId;
+                foundParentLibrary = true;
+                break;
+            }
+        }
+        if (!foundParentLibrary) {
+            break;
+        }
+    }
+    return pathSegments.length > 0 ? pathSegments.join('/') : undefined;
+}
+/**
+ * Batch-resolves library paths for multiple documents.
+ * More efficient than calling resolveDocumentLibraryPath individually
+ * since it can reuse cached library lookups.
+ *
+ * @param api - API for querying dependencies and elements
+ * @param documentIds - Array of document element IDs
+ * @returns Map from document ID to library path (undefined entries omitted)
+ */
+export async function resolveDocumentLibraryPaths(api, documentIds) {
+    const result = new Map();
+    for (const docId of documentIds) {
+        const libraryPath = await resolveDocumentLibraryPath(api, docId);
+        if (libraryPath) {
+            result.set(docId, libraryPath);
+        }
+    }
+    return result;
+}
+// ============================================================================
+// Push: Stoneforge Document → External Document
+// ============================================================================
+/**
+ * Converts a Stoneforge Document into an ExternalDocumentInput for
+ * creating/updating a page in an external system.
+ *
+ * Handles:
+ * - Title mapping (1:1, falls back to empty string if undefined)
+ * - Content mapping (1:1)
+ * - ContentType mapping (markdown/text → markdown/text, json → text)
+ * - Optional library path for directory-based organization
+ *
+ * @param doc - The Stoneforge document to convert
+ * @param libraryPath - Optional pre-computed library path for the document
+ * @returns ExternalDocumentInput ready for the provider adapter
+ */
+export function documentToExternalDocumentInput(doc, libraryPath) {
+    return {
+        title: doc.title ?? '',
+        content: doc.content,
+        contentType: mapContentTypeToExternal(doc.contentType),
+        ...(doc.category !== undefined && { category: doc.category }),
+        ...(doc.tags !== undefined && doc.tags.length > 0 && { tags: doc.tags }),
+        ...(libraryPath !== undefined && { libraryPath }),
+    };
+}
+// ============================================================================
+// Pull: External Document → Stoneforge Document Updates
+// ============================================================================
+/**
+ * Converts an ExternalDocument into a partial Document update object for
+ * applying external changes to a local Stoneforge document.
+ *
+ * Handles:
+ * - Title mapping (1:1)
+ * - Content mapping (1:1)
+ * - ContentType mapping (markdown/text/html → markdown/text/text)
+ *
+ * If existingDoc is provided, only changed fields are returned (diff mode).
+ * If existingDoc is undefined, all mappable fields are returned (create mode).
+ *
+ * @param externalDoc - The external document to convert
+ * @param existingDoc - The existing local document (undefined for new documents)
+ * @returns Partial<Document> with only the changed fields (or all fields if no existingDoc)
+ */
+export function externalDocumentToDocumentUpdates(externalDoc, existingDoc) {
+    const contentType = mapContentTypeFromExternal(externalDoc.contentType);
+    const fullUpdate = {
+        title: externalDoc.title,
+        content: externalDoc.content,
+        contentType,
+    };
+    // If no existing document, return full create input
+    if (!existingDoc) {
+        return fullUpdate;
+    }
+    // Diff mode: only return changed fields
+    return diffDocumentUpdates(existingDoc, fullUpdate);
+}
+// ============================================================================
+// Diff Utilities
+// ============================================================================
+/**
+ * Compares a full update against an existing document 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.
+ *
+ * Compared fields: title, content, contentType, category, tags
+ */
+export function diffDocumentUpdates(existing, updates) {
+    const diff = {};
+    if (updates.title !== undefined && updates.title !== existing.title) {
+        diff.title = updates.title;
+    }
+    if (updates.content !== undefined && updates.content !== existing.content) {
+        diff.content = updates.content;
+    }
+    if (updates.contentType !== undefined &&
+        updates.contentType !== existing.contentType) {
+        diff.contentType = updates.contentType;
+    }
+    if (updates.category !== undefined &&
+        updates.category !== existing.category) {
+        diff.category = updates.category;
+    }
+    if (updates.tags !== undefined && !arraysEqual(updates.tags, existing.tags)) {
+        diff.tags = updates.tags;
+    }
+    return diff;
+}
+// ============================================================================
+// Hash Computation
+// ============================================================================
+/**
+ * Computes a deterministic hash of an ExternalDocument for change detection.
+ *
+ * The hash is based on the document's title, content, and contentType.
+ * Used by the sync engine to detect whether an external document has
+ * changed since the last sync, avoiding unnecessary pull operations.
+ *
+ * @param doc - The external document to hash
+ * @returns A hex-encoded SHA-256 hash string
+ */
+export function computeExternalDocumentHash(doc) {
+    const hash = createHash('sha256');
+    hash.update(doc.title);
+    hash.update('\0'); // null byte separator to avoid collisions
+    hash.update(doc.content);
+    hash.update('\0');
+    hash.update(doc.contentType);
+    return hash.digest('hex');
+}
+// ============================================================================
+// Internal Helpers
+// ============================================================================
+/**
+ * Compares two arrays for equality (order-independent).
+ */
+function arraysEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    const sortedA = [...a].sort();
+    const sortedB = [...b].sort();
+    return sortedA.every((val, idx) => val === sortedB[idx]);
+}
+//# sourceMappingURL=document-sync-adapter.js.map

package/dist/external-sync/adapters/document-sync-adapter.js.map

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

package/dist/external-sync/adapters/task-sync-adapter.d.ts

@@ -0,0 +1,177 @@
+/**
+ * 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

package/dist/external-sync/adapters/task-sync-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-sync-adapter.d.ts","sourceRoot":"","sources":["../../../src/external-sync/adapters/task-sync-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EACV,IAAI,EACJ,UAAU,EACV,QAAQ,EACR,aAAa,EACb,UAAU,EAEV,OAAO,EAEP,SAAS,EACV,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AASxE;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,CAAC,SAAS,OAAO,EAAE,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;CAC1D;AAMD;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAElD;;;OAGG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC;IAEvD;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE/C;;;;;OAKG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IAEjC;;;;OAIG;IACH,QAAQ,CAAC,aAAa,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,MAAM,GAAG,QAAQ,CAAC;IAElE;;;;OAIG;IACH,QAAQ,CAAC,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,UAAU,CAAC;CACpF;AAMD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,sBAAsB,EAC9B,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,iBAAiB,CAAC,CAuB5B;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,yBAAyB,CACvC,YAAY,EAAE,YAAY,EAC1B,YAAY,EAAE,IAAI,GAAG,SAAS,EAC9B,MAAM,EAAE,sBAAsB,GAC7B,OAAO,CAAC,IAAI,CAAC,CA8Cf;AAMD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,sBAAsB,GAC7B,MAAM,EAAE,CAwCV;AAMD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,wEAAwE;IACxE,QAAQ,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC/B,0EAA0E;IAC1E,QAAQ,EAAE,aAAa,GAAG,SAAS,CAAC;IACpC,oEAAoE;IACpE,MAAM,EAAE,UAAU,GAAG,SAAS,CAAC;IAC/B,mDAAmD;IACnD,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,MAAM,EAAE,sBAAsB,GAC7B,oBAAoB,CAiDtB;AAMD;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,cAAc,EAAE,UAAU,GAAG,SAAS,EACtC,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAW7B;AAqCD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,YAAY,EAAE,IAAI,EAClB,UAAU,EAAE,OAAO,CAAC,IAAI,CAAC,GACxB,OAAO,CAAC,IAAI,CAAC,CAoCf;AAsCD;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAAC,YAAY,EAAE,MAAM,GAAG,sBAAsB,CAUzF"}