@stoneforge/quarry 1.12.0 → 1.14.0

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

@@ -0,0 +1,353 @@
+/**
+ * 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 { GITHUB_FIELD_MAP_CONFIG } from '../providers/github/github-field-map.js';
+import { createLinearSyncFieldMapConfig, shouldAddBlockedLabel } from '../providers/linear/linear-field-map.js';
+// ============================================================================
+// Push: Stoneforge Task → External Task
+// ============================================================================
+/**
+ * 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 async function taskToExternalTask(task, config, api) {
+    // Map title (1:1)
+    const title = task.title;
+    // Map status → state
+    const state = config.statusToState(task.status);
+    // Build labels from sync-managed fields + user tags
+    const labels = buildExternalLabels(task, config);
+    // Hydrate description from descriptionRef document
+    const body = await hydrateDescription(task.descriptionRef, api);
+    return {
+        title,
+        body,
+        state,
+        labels,
+        // Assignees are intentionally omitted — Stoneforge assignees are ephemeral
+        // agents (e.g., el-xxxx) that don't map to valid external system users.
+        assignees: undefined,
+        priority: task.priority,
+    };
+}
+// ============================================================================
+// Pull: External Task → Stoneforge Task Updates
+// ============================================================================
+/**
+ * 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 function externalTaskToTaskUpdates(externalTask, existingTask, config) {
+    // Parse external labels into structured data
+    const parsed = parseExternalLabels(externalTask.labels, config);
+    // Map state + labels → status
+    const status = config.stateToStatus(externalTask.state, [...externalTask.labels]);
+    // Map priority: prefer native priority from the ExternalTask (set by providers
+    // with native priority support like Linear), fall back to label-based extraction,
+    // then default to medium (3) if neither is available.
+    const priority = externalTask.priority ?? parsed.priority ?? 3;
+    // Map task type from labels (default to 'task' if not found)
+    const taskType = parsed.taskType ?? 'task';
+    // User tags = all labels that aren't sync-managed
+    const tags = parsed.userTags;
+    // Build the full update object
+    const fullUpdate = {
+        title: externalTask.title,
+        status,
+        priority: priority,
+        taskType: taskType,
+        tags,
+    };
+    // Map first assignee if present
+    if (externalTask.assignees.length > 0) {
+        // Store assignee name in metadata for resolution by the sync engine
+        // The sync engine is responsible for looking up the EntityId
+        fullUpdate.metadata = {
+            _pendingAssignee: externalTask.assignees[0],
+        };
+    }
+    // Map external ref URL
+    fullUpdate.externalRef = externalTask.url;
+    // If no existing task, return full create input
+    if (!existingTask) {
+        return fullUpdate;
+    }
+    // Diff mode: only return changed fields
+    return diffTaskUpdates(existingTask, fullUpdate);
+}
+// ============================================================================
+// Label Building (Push)
+// ============================================================================
+/**
+ * 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 function buildExternalLabels(task, config) {
+    const labels = [];
+    const prefix = config.syncLabelPrefix;
+    // Add priority label
+    const priorityLabel = config.priorityLabels[task.priority];
+    if (priorityLabel) {
+        labels.push(`${prefix}${priorityLabel}`);
+    }
+    // Add task type label
+    const taskTypeLabel = config.taskTypeLabels[task.taskType];
+    if (taskTypeLabel) {
+        labels.push(`${prefix}${taskTypeLabel}`);
+    }
+    // Add status label (when config.statusLabels is present)
+    if (config.statusLabels) {
+        const statusLabel = config.statusLabels[task.status];
+        if (statusLabel) {
+            labels.push(`${prefix}${statusLabel}`);
+        }
+    }
+    // Add a plain "blocked" label when the task has blocked status.
+    // This label is used by provider adapters (e.g., LinearTaskAdapter) to detect
+    // blocked tasks and apply provider-specific handling (e.g., adding a native
+    // "blocked" label on Linear, mapping to 'started' state type instead of
+    // 'unstarted'). The label is always added regardless of statusLabels —
+    // adapters need this signal to properly handle blocked tasks.
+    if (shouldAddBlockedLabel(task.status)) {
+        labels.push('blocked');
+    }
+    // Add user tags (not prefixed — these are user-managed)
+    for (const tag of task.tags) {
+        labels.push(tag);
+    }
+    return labels;
+}
+/**
+ * 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 function parseExternalLabels(labels, config) {
+    const prefix = config.syncLabelPrefix;
+    let priority;
+    let taskType;
+    let status;
+    const userTags = [];
+    // Build reverse lookup maps for priority and task type
+    const priorityByLabel = buildReverseLookup(config.priorityLabels);
+    const taskTypeByLabel = buildReverseLookup(config.taskTypeLabels);
+    // Build reverse lookup for status labels (when present)
+    const statusByLabel = config.statusLabels
+        ? buildReverseLookup(config.statusLabels)
+        : undefined;
+    for (const label of labels) {
+        if (label.startsWith(prefix)) {
+            // This is a sync-managed label — extract the value part
+            const value = label.slice(prefix.length);
+            // Check if it's a priority label
+            if (priorityByLabel.has(value)) {
+                priority = priorityByLabel.get(value);
+                continue;
+            }
+            // Check if it's a task type label
+            if (taskTypeByLabel.has(value)) {
+                taskType = taskTypeByLabel.get(value);
+                continue;
+            }
+            // Check if it's a status label
+            if (statusByLabel && statusByLabel.has(value)) {
+                status = statusByLabel.get(value);
+                continue;
+            }
+            // Sync-managed label we don't recognize — skip it
+            // (could be from a newer version or a different adapter)
+            continue;
+        }
+        // Not a sync-managed label — treat as user tag
+        userTags.push(label);
+    }
+    return { priority, taskType, status, userTags };
+}
+// ============================================================================
+// Description Handling
+// ============================================================================
+/**
+ * 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 async function hydrateDescription(descriptionRef, api) {
+    if (!descriptionRef) {
+        return undefined;
+    }
+    const doc = await api.get(descriptionRef);
+    if (!doc || doc.type !== 'document') {
+        return undefined;
+    }
+    return doc.content || undefined;
+}
+/**
+ * Resolves task assignee to an external-friendly name.
+ *
+ * @deprecated No longer used — Stoneforge assignees are ephemeral agents
+ * that don't map to valid users on external platforms. Assignee writing
+ * to external systems has been removed. This function is kept temporarily
+ * for reference but will be removed in a future cleanup.
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+async function resolveAssignees(task, api) {
+    if (!task.assignee) {
+        return [];
+    }
+    const entity = await api.get(task.assignee);
+    if (!entity || entity.type !== 'entity') {
+        return [];
+    }
+    // Entity has a 'name' field
+    const name = entity.name;
+    if (typeof name === 'string') {
+        return [name];
+    }
+    return [];
+}
+// ============================================================================
+// Diff Utilities
+// ============================================================================
+/**
+ * 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 function diffTaskUpdates(existingTask, fullUpdate) {
+    const diff = {};
+    if (fullUpdate.title !== undefined && fullUpdate.title !== existingTask.title) {
+        diff.title = fullUpdate.title;
+    }
+    if (fullUpdate.status !== undefined && fullUpdate.status !== existingTask.status) {
+        diff.status = fullUpdate.status;
+    }
+    if (fullUpdate.priority !== undefined && fullUpdate.priority !== existingTask.priority) {
+        diff.priority = fullUpdate.priority;
+    }
+    if (fullUpdate.taskType !== undefined && fullUpdate.taskType !== existingTask.taskType) {
+        diff.taskType = fullUpdate.taskType;
+    }
+    if (fullUpdate.tags !== undefined && !arraysEqual(fullUpdate.tags, existingTask.tags)) {
+        diff.tags = fullUpdate.tags;
+    }
+    if (fullUpdate.externalRef !== undefined && fullUpdate.externalRef !== existingTask.externalRef) {
+        diff.externalRef = fullUpdate.externalRef;
+    }
+    // Include metadata if there's a pending assignee
+    if (fullUpdate.metadata !== undefined) {
+        const pendingAssignee = fullUpdate.metadata?._pendingAssignee;
+        if (pendingAssignee !== undefined) {
+            diff.metadata = fullUpdate.metadata;
+        }
+    }
+    return diff;
+}
+// ============================================================================
+// Internal Helpers
+// ============================================================================
+/**
+ * Builds a reverse lookup map from a Record<K, V> to Map<V, K>.
+ * Used to look up priority/task type values from their label strings.
+ */
+function buildReverseLookup(record) {
+    const map = new Map();
+    for (const [key, value] of Object.entries(record)) {
+        // Keys from Record<Priority, string> come as strings from Object.entries
+        // Need to convert numeric keys back to numbers
+        const typedKey = isNaN(Number(key)) ? key : Number(key);
+        map.set(value, typedKey);
+    }
+    return map;
+}
+/**
+ * Compares two arrays for shallow equality (order-sensitive).
+ */
+function arraysEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    // Sort copies for order-independent comparison
+    const sortedA = [...a].sort();
+    const sortedB = [...b].sort();
+    return sortedA.every((val, idx) => val === sortedB[idx]);
+}
+// ============================================================================
+// Provider Field Map Config Lookup
+// ============================================================================
+/**
+ * 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 function getFieldMapConfigForProvider(providerName) {
+    switch (providerName) {
+        case 'github':
+            return GITHUB_FIELD_MAP_CONFIG;
+        case 'linear':
+            return createLinearSyncFieldMapConfig();
+        default:
+            // Fallback to GitHub-style config for unknown providers
+            return GITHUB_FIELD_MAP_CONFIG;
+    }
+}
+//# sourceMappingURL=task-sync-adapter.js.map

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

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

package/dist/external-sync/auto-link.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Auto-Link Utility
+ *
+ * Creates an external issue on a configured provider and links it back to
+ * a Stoneforge task via `externalRef` and `_externalSync` metadata.
+ *
+ * Designed to be called after task creation in a fire-and-forget pattern.
+ * Never throws — all errors are caught and returned as `{ success: false, error }`.
+ */
+import type { Task, ExternalProvider, ExternalSyncState, SyncDirection } from '@stoneforge/core';
+import type { QuarryAPI } from '../api/types.js';
+/**
+ * Parameters for autoLinkTask()
+ */
+export interface AutoLinkTaskParams {
+    /** The newly created task to auto-link */
+    task: Task;
+    /** QuarryAPI instance for updating the task */
+    api: QuarryAPI;
+    /** Configured external provider instance (e.g., GitHub, Linear) */
+    provider: ExternalProvider;
+    /** Project identifier (e.g., 'owner/repo' for GitHub, team key for Linear) */
+    project: string;
+    /** Sync direction to set on the link */
+    direction: SyncDirection;
+}
+/**
+ * Result of autoLinkTask()
+ */
+export interface AutoLinkTaskResult {
+    /** Whether the auto-link succeeded */
+    success: boolean;
+    /** The ExternalSyncState set on the task (only on success) */
+    syncState?: ExternalSyncState;
+    /** Error message (only on failure) */
+    error?: string;
+}
+/**
+ * Auto-link a newly created task to an external issue.
+ *
+ * Creates an issue on the configured provider and updates the Stoneforge task
+ * with `externalRef` and `_externalSync` metadata.
+ *
+ * **Never throws** — catches all errors and returns `{ success: false, error }`.
+ * Auto-link failure must not prevent task creation.
+ *
+ * @param params - The auto-link parameters
+ * @returns Result indicating success or failure with details
+ *
+ * @example
+ * ```typescript
+ * const result = await autoLinkTask({
+ *   task,
+ *   api,
+ *   provider: githubProvider,
+ *   project: 'owner/repo',
+ *   direction: 'bidirectional',
+ * });
+ *
+ * if (!result.success) {
+ *   console.warn('Auto-link failed:', result.error);
+ * }
+ * ```
+ */
+export declare function autoLinkTask(params: AutoLinkTaskParams): Promise<AutoLinkTaskResult>;
+//# sourceMappingURL=auto-link.d.ts.map

package/dist/external-sync/auto-link.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-link.d.ts","sourceRoot":"","sources":["../../src/external-sync/auto-link.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,IAAI,EACJ,gBAAgB,EAEhB,iBAAiB,EACjB,aAAa,EAEd,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AASjD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,0CAA0C;IAC1C,IAAI,EAAE,IAAI,CAAC;IACX,+CAA+C;IAC/C,GAAG,EAAE,SAAS,CAAC;IACf,mEAAmE;IACnE,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,SAAS,EAAE,aAAa,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,sCAAsC;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAC9B,sCAAsC;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAkE1F"}

package/dist/external-sync/auto-link.js

@@ -0,0 +1,98 @@
+/**
+ * Auto-Link Utility
+ *
+ * Creates an external issue on a configured provider and links it back to
+ * a Stoneforge task via `externalRef` and `_externalSync` metadata.
+ *
+ * Designed to be called after task creation in a fire-and-forget pattern.
+ * Never throws — all errors are caught and returned as `{ success: false, error }`.
+ */
+import { taskToExternalTask, getFieldMapConfigForProvider } from './adapters/task-sync-adapter.js';
+const LOG_PREFIX = '[external-sync]';
+// ============================================================================
+// Auto-Link Function
+// ============================================================================
+/**
+ * Auto-link a newly created task to an external issue.
+ *
+ * Creates an issue on the configured provider and updates the Stoneforge task
+ * with `externalRef` and `_externalSync` metadata.
+ *
+ * **Never throws** — catches all errors and returns `{ success: false, error }`.
+ * Auto-link failure must not prevent task creation.
+ *
+ * @param params - The auto-link parameters
+ * @returns Result indicating success or failure with details
+ *
+ * @example
+ * ```typescript
+ * const result = await autoLinkTask({
+ *   task,
+ *   api,
+ *   provider: githubProvider,
+ *   project: 'owner/repo',
+ *   direction: 'bidirectional',
+ * });
+ *
+ * if (!result.success) {
+ *   console.warn('Auto-link failed:', result.error);
+ * }
+ * ```
+ */
+export async function autoLinkTask(params) {
+    const { task, api, provider, project, direction } = params;
+    try {
+        // 1. Get the provider's task adapter
+        const adapter = provider.getTaskAdapter?.();
+        if (!adapter) {
+            const message = `Provider '${provider.name}' does not support task sync`;
+            console.warn(`${LOG_PREFIX} Auto-link failed for task ${task.id}: ${message}`);
+            return { success: false, error: message };
+        }
+        // 2. Build full ExternalTaskInput via taskToExternalTask, with fallback
+        let issueInput;
+        try {
+            const fieldMapConfig = getFieldMapConfigForProvider(provider.name);
+            issueInput = await taskToExternalTask(task, fieldMapConfig, api);
+        }
+        catch (mappingErr) {
+            // Fallback to simplified input so auto-link still succeeds
+            console.warn(`${LOG_PREFIX} Full field mapping failed for task ${task.id}, using simplified input: ${mappingErr instanceof Error ? mappingErr.message : String(mappingErr)}`);
+            issueInput = {
+                title: task.title,
+                body: task.descriptionRef ? `Stoneforge task: ${task.id}` : undefined,
+                labels: task.tags ? [...task.tags] : undefined,
+            };
+        }
+        // 3. Create the external issue
+        const externalTask = await adapter.createIssue(project, issueInput);
+        // 4. Build the ExternalSyncState metadata
+        const syncState = {
+            provider: provider.name,
+            project,
+            externalId: externalTask.externalId,
+            url: externalTask.url,
+            direction,
+            adapterType: 'task',
+        };
+        // 5. Update the task with externalRef and _externalSync metadata
+        const existingMetadata = (task.metadata ?? {});
+        await api.update(task.id, {
+            externalRef: externalTask.url,
+            metadata: {
+                ...existingMetadata,
+                _externalSync: syncState,
+            },
+        });
+        console.info(`${LOG_PREFIX} Auto-linked task ${task.id} to ${provider.name} issue ${externalTask.externalId} (${externalTask.url})`);
+        // 6. Return success
+        return { success: true, syncState };
+    }
+    catch (err) {
+        // 7. Never throw — catch all errors and return failure
+        const message = err instanceof Error ? err.message : String(err);
+        console.warn(`${LOG_PREFIX} Auto-link failed for task ${task.id}: ${message}`);
+        return { success: false, error: message };
+    }
+}
+//# sourceMappingURL=auto-link.js.map

package/dist/external-sync/auto-link.js.map

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