@stoneforge/quarry 1.12.0 → 1.14.0

package/dist/external-sync/providers/github/github-field-map.d.ts

@@ -0,0 +1,76 @@
+/**
+ * GitHub Field Map Configuration
+ *
+ * Defines how Stoneforge task fields map to GitHub issue fields.
+ * Used by the GitHubTaskAdapter and the shared task sync adapter utilities.
+ *
+ * Key mappings:
+ * - Priority (1-5) -> labels with 'priority:' prefix
+ * - TaskType (bug/feature/task/chore) -> labels with 'type:' prefix
+ * - Status -> GitHub issue state ('open' or 'closed')
+ * - Tags -> labels (user-managed, no prefix)
+ * - Sync-managed labels use the 'sf:' prefix
+ */
+import type { TaskStatus, Priority, TaskTypeValue } from '@stoneforge/core';
+import type { TaskSyncFieldMapConfig } from '../../adapters/task-sync-adapter.js';
+/**
+ * Maps Stoneforge priority values (1-5) to GitHub label names.
+ * These labels are prefixed with 'sf:' when pushed to GitHub to
+ * distinguish sync-managed labels from user-created labels.
+ */
+export declare const GITHUB_PRIORITY_LABELS: Record<Priority, string>;
+/**
+ * Maps Stoneforge task type values to GitHub label names.
+ * These labels are prefixed with 'sf:' when pushed to GitHub.
+ */
+export declare const GITHUB_TASK_TYPE_LABELS: Record<TaskTypeValue, string>;
+/**
+ * Prefix for Stoneforge-managed labels on GitHub issues.
+ * Labels with this prefix are created and managed by the sync system.
+ * User labels without this prefix are preserved during sync.
+ */
+export declare const GITHUB_SYNC_LABEL_PREFIX = "sf:";
+/**
+ * Maps Stoneforge TaskStatus values to GitHub label names.
+ * These labels are prefixed with 'sf:' when pushed to GitHub to
+ * provide granular status visibility beyond GitHub's binary open/closed state.
+ */
+export declare const GITHUB_STATUS_LABELS: Record<TaskStatus, string>;
+/**
+ * Maps Stoneforge TaskStatus to GitHub issue state.
+ *
+ * GitHub only supports two issue states: 'open' and 'closed'.
+ * Most Stoneforge statuses map to 'open' since GitHub can't
+ * distinguish between open, in_progress, review, blocked, etc.
+ *
+ * Mapping:
+ * - open, in_progress, review, blocked, deferred, backlog -> 'open'
+ * - closed, tombstone -> 'closed'
+ */
+export declare function statusToGitHubState(status: TaskStatus): 'open' | 'closed';
+/**
+ * Maps GitHub issue state + labels back to Stoneforge TaskStatus.
+ *
+ * Uses sf:status:* labels for granular status inference when available.
+ * If a status label is found, it takes precedence over the basic
+ * open/closed state mapping. Falls back to the simple state mapping
+ * when no status label is present.
+ *
+ * Mapping with labels:
+ * - 'sf:status:in-progress' → 'in_progress'
+ * - 'sf:status:blocked' → 'blocked'
+ * - etc.
+ *
+ * Fallback mapping (no status label):
+ * - 'open' → 'open'
+ * - 'closed' → 'closed'
+ */
+export declare function gitHubStateToStatus(state: 'open' | 'closed', labels: string[]): TaskStatus;
+/**
+ * Complete GitHub-specific field mapping configuration.
+ *
+ * Used by the shared task sync adapter utilities to convert between
+ * Stoneforge tasks and GitHub issues (in both push and pull directions).
+ */
+export declare const GITHUB_FIELD_MAP_CONFIG: TaskSyncFieldMapConfig;
+//# sourceMappingURL=github-field-map.d.ts.map

package/dist/external-sync/providers/github/github-field-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-field-map.d.ts","sourceRoot":"","sources":["../../../../src/external-sync/providers/github/github-field-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAC5E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAC;AAMlF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAM/B,CAAC;AAM9B;;;GAGG;AACH,eAAO,MAAM,uBAAuB,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,CAKhC,CAAC;AAMnC;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,QAAQ,CAAC;AAM9C;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,CAS3D,CAAC;AAMF;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,GAAG,QAAQ,CAczE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,GAAG,QAAQ,EACxB,MAAM,EAAE,MAAM,EAAE,GACf,UAAU,CA0BZ;AAMD;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,EAAE,sBAOrC,CAAC"}

package/dist/external-sync/providers/github/github-field-map.js

@@ -0,0 +1,157 @@
+/**
+ * GitHub Field Map Configuration
+ *
+ * Defines how Stoneforge task fields map to GitHub issue fields.
+ * Used by the GitHubTaskAdapter and the shared task sync adapter utilities.
+ *
+ * Key mappings:
+ * - Priority (1-5) -> labels with 'priority:' prefix
+ * - TaskType (bug/feature/task/chore) -> labels with 'type:' prefix
+ * - Status -> GitHub issue state ('open' or 'closed')
+ * - Tags -> labels (user-managed, no prefix)
+ * - Sync-managed labels use the 'sf:' prefix
+ */
+// ============================================================================
+// Priority Label Mapping
+// ============================================================================
+/**
+ * Maps Stoneforge priority values (1-5) to GitHub label names.
+ * These labels are prefixed with 'sf:' when pushed to GitHub to
+ * distinguish sync-managed labels from user-created labels.
+ */
+export const GITHUB_PRIORITY_LABELS = {
+    1: 'priority:critical',
+    2: 'priority:high',
+    3: 'priority:medium',
+    4: 'priority:low',
+    5: 'priority:minimal',
+};
+// ============================================================================
+// Task Type Label Mapping
+// ============================================================================
+/**
+ * Maps Stoneforge task type values to GitHub label names.
+ * These labels are prefixed with 'sf:' when pushed to GitHub.
+ */
+export const GITHUB_TASK_TYPE_LABELS = {
+    bug: 'type:bug',
+    feature: 'type:feature',
+    task: 'type:task',
+    chore: 'type:chore',
+};
+// ============================================================================
+// Sync Label Prefix
+// ============================================================================
+/**
+ * Prefix for Stoneforge-managed labels on GitHub issues.
+ * Labels with this prefix are created and managed by the sync system.
+ * User labels without this prefix are preserved during sync.
+ */
+export const GITHUB_SYNC_LABEL_PREFIX = 'sf:';
+// ============================================================================
+// Status Label Mapping
+// ============================================================================
+/**
+ * Maps Stoneforge TaskStatus values to GitHub label names.
+ * These labels are prefixed with 'sf:' when pushed to GitHub to
+ * provide granular status visibility beyond GitHub's binary open/closed state.
+ */
+export const GITHUB_STATUS_LABELS = {
+    open: 'status:open',
+    in_progress: 'status:in-progress',
+    blocked: 'status:blocked',
+    deferred: 'status:deferred',
+    backlog: 'status:backlog',
+    review: 'status:review',
+    closed: 'status:closed',
+    tombstone: 'status:tombstone',
+};
+// ============================================================================
+// Status <-> State Mapping
+// ============================================================================
+/**
+ * Maps Stoneforge TaskStatus to GitHub issue state.
+ *
+ * GitHub only supports two issue states: 'open' and 'closed'.
+ * Most Stoneforge statuses map to 'open' since GitHub can't
+ * distinguish between open, in_progress, review, blocked, etc.
+ *
+ * Mapping:
+ * - open, in_progress, review, blocked, deferred, backlog -> 'open'
+ * - closed, tombstone -> 'closed'
+ */
+export function statusToGitHubState(status) {
+    switch (status) {
+        case 'closed':
+        case 'tombstone':
+            return 'closed';
+        case 'open':
+        case 'in_progress':
+        case 'review':
+        case 'blocked':
+        case 'deferred':
+        case 'backlog':
+        default:
+            return 'open';
+    }
+}
+/**
+ * Maps GitHub issue state + labels back to Stoneforge TaskStatus.
+ *
+ * Uses sf:status:* labels for granular status inference when available.
+ * If a status label is found, it takes precedence over the basic
+ * open/closed state mapping. Falls back to the simple state mapping
+ * when no status label is present.
+ *
+ * Mapping with labels:
+ * - 'sf:status:in-progress' → 'in_progress'
+ * - 'sf:status:blocked' → 'blocked'
+ * - etc.
+ *
+ * Fallback mapping (no status label):
+ * - 'open' → 'open'
+ * - 'closed' → 'closed'
+ */
+export function gitHubStateToStatus(state, labels) {
+    // Build a reverse lookup from status labels: 'status:open' → 'open', etc.
+    const statusByLabel = new Map();
+    for (const [status, label] of Object.entries(GITHUB_STATUS_LABELS)) {
+        statusByLabel.set(label, status);
+    }
+    // Check labels for a status label (strip the sync prefix first)
+    for (const label of labels) {
+        if (label.startsWith(GITHUB_SYNC_LABEL_PREFIX)) {
+            const value = label.slice(GITHUB_SYNC_LABEL_PREFIX.length);
+            const matchedStatus = statusByLabel.get(value);
+            if (matchedStatus !== undefined) {
+                return matchedStatus;
+            }
+        }
+    }
+    // Fallback: basic open/closed mapping
+    switch (state) {
+        case 'closed':
+            return 'closed';
+        case 'open':
+        default:
+            return 'open';
+    }
+}
+// ============================================================================
+// Combined Field Map Config
+// ============================================================================
+/**
+ * Complete GitHub-specific field mapping configuration.
+ *
+ * Used by the shared task sync adapter utilities to convert between
+ * Stoneforge tasks and GitHub issues (in both push and pull directions).
+ */
+export const GITHUB_FIELD_MAP_CONFIG = {
+    priorityLabels: GITHUB_PRIORITY_LABELS,
+    taskTypeLabels: GITHUB_TASK_TYPE_LABELS,
+    statusLabels: GITHUB_STATUS_LABELS,
+    syncLabelPrefix: GITHUB_SYNC_LABEL_PREFIX,
+    statusToState: statusToGitHubState,
+    stateToStatus: gitHubStateToStatus,
+};
+//# sourceMappingURL=github-field-map.js.map

package/dist/external-sync/providers/github/github-field-map.js.map

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

package/dist/external-sync/providers/github/github-provider.d.ts

@@ -0,0 +1,36 @@
+/**
+ * GitHub Provider
+ *
+ * Full implementation of the GitHub ExternalProvider.
+ * Handles connection testing via the GitHub API and provides
+ * a TaskSyncAdapter for bidirectional task/issue synchronization.
+ *
+ * The provider uses a lazy-initialized GitHubTaskAdapter that
+ * requires a ProviderConfig with a valid token before use.
+ *
+ * Also exports the placeholder provider for backward compatibility
+ * with systems that register the provider before configuration.
+ */
+import type { ExternalProvider, ProviderConfig } from '@stoneforge/core';
+/**
+ * Create a configured GitHub provider.
+ *
+ * The provider is ready to use for sync operations when a valid
+ * token is provided in the config. The task adapter is initialized
+ * immediately with the provided credentials.
+ *
+ * @param config - Provider configuration with token and optional apiBaseUrl
+ * @returns A fully configured GitHub ExternalProvider
+ */
+export declare function createGitHubProvider(config: ProviderConfig): ExternalProvider;
+/**
+ * Create a placeholder GitHub provider.
+ *
+ * The provider is registered by default in the provider registry so that
+ * the system knows GitHub is an available provider. Connection testing
+ * always returns false and all adapter methods throw until configured.
+ *
+ * @returns A placeholder GitHub ExternalProvider
+ */
+export declare function createGitHubPlaceholderProvider(): ExternalProvider;
+//# sourceMappingURL=github-provider.d.ts.map

package/dist/external-sync/providers/github/github-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-provider.d.ts","sourceRoot":"","sources":["../../../../src/external-sync/providers/github/github-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,cAAc,EAMf,MAAM,kBAAkB,CAAC;AA4M1B;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,cAAc,GAAG,gBAAgB,CAE7E;AAED;;;;;;;;GAQG;AACH,wBAAgB,+BAA+B,IAAI,gBAAgB,CAElE"}

package/dist/external-sync/providers/github/github-provider.js

@@ -0,0 +1,212 @@
+/**
+ * GitHub Provider
+ *
+ * Full implementation of the GitHub ExternalProvider.
+ * Handles connection testing via the GitHub API and provides
+ * a TaskSyncAdapter for bidirectional task/issue synchronization.
+ *
+ * The provider uses a lazy-initialized GitHubTaskAdapter that
+ * requires a ProviderConfig with a valid token before use.
+ *
+ * Also exports the placeholder provider for backward compatibility
+ * with systems that register the provider before configuration.
+ */
+import { GitHubTaskAdapter } from './github-task-adapter.js';
+// ============================================================================
+// GitHub Provider (Full Implementation)
+// ============================================================================
+/**
+ * GitHub ExternalProvider implementation.
+ *
+ * Provides connection testing and a TaskSyncAdapter for GitHub Issues.
+ * The task adapter is created on demand with the configured token.
+ *
+ * Usage:
+ * ```typescript
+ * const provider = createGitHubProvider({ token: 'ghp_...' });
+ * const connected = await provider.testConnection(config);
+ * const adapter = provider.getTaskAdapter();
+ * ```
+ */
+class GitHubProvider {
+    name = 'github';
+    displayName = 'GitHub';
+    supportedAdapters = ['task'];
+    taskAdapter = null;
+    config;
+    constructor(config) {
+        this.config = config;
+        // Initialize the task adapter if a token is available
+        if (config.token) {
+            this.taskAdapter = new GitHubTaskAdapter({
+                token: config.token,
+                apiBaseUrl: config.apiBaseUrl,
+            });
+        }
+    }
+    /**
+     * Test whether the GitHub connection is valid by calling GET /user.
+     *
+     * This verifies that the configured token is valid and has the
+     * necessary permissions to access the GitHub API.
+     *
+     * @param config - Provider configuration with token to test
+     * @returns true if the connection is valid, false otherwise
+     */
+    async testConnection(config) {
+        if (!config.token) {
+            return false;
+        }
+        const baseUrl = (config.apiBaseUrl ?? 'https://api.github.com').replace(/\/$/, '');
+        try {
+            const response = await fetch(`${baseUrl}/user`, {
+                method: 'GET',
+                headers: {
+                    Authorization: `Bearer ${config.token}`,
+                    Accept: 'application/vnd.github+json',
+                    'X-GitHub-Api-Version': '2022-11-28',
+                },
+            });
+            return response.ok;
+        }
+        catch {
+            // Network errors, DNS failures, etc.
+            return false;
+        }
+    }
+    /**
+     * Returns the GitHubTaskAdapter instance.
+     *
+     * The adapter is initialized with the token from the provider config.
+     * Throws if no token was configured (provider not yet set up).
+     *
+     * @returns GitHubTaskAdapter for GitHub Issues sync
+     * @throws Error if no token is configured
+     */
+    getTaskAdapter() {
+        if (!this.taskAdapter) {
+            throw new Error('GitHub provider is not configured. Set a token via provider config before using the task adapter.');
+        }
+        return this.taskAdapter;
+    }
+}
+// ============================================================================
+// Placeholder Provider (Backward Compatibility)
+// ============================================================================
+/**
+ * Placeholder TaskSyncAdapter for GitHub.
+ * All methods throw to indicate they are not yet implemented.
+ * Used when the provider is registered without configuration.
+ */
+class GitHubPlaceholderTaskAdapter {
+    static PLACEHOLDER_MESSAGE = 'GitHub task sync adapter is not configured. Set a token via provider config to enable sync.';
+    async getIssue(_project, _externalId) {
+        throw new Error(GitHubPlaceholderTaskAdapter.PLACEHOLDER_MESSAGE);
+    }
+    async listIssuesSince(_project, _since) {
+        throw new Error(GitHubPlaceholderTaskAdapter.PLACEHOLDER_MESSAGE);
+    }
+    async createIssue(_project, _issue) {
+        throw new Error(GitHubPlaceholderTaskAdapter.PLACEHOLDER_MESSAGE);
+    }
+    async updateIssue(_project, _externalId, _updates) {
+        throw new Error(GitHubPlaceholderTaskAdapter.PLACEHOLDER_MESSAGE);
+    }
+    getFieldMapConfig() {
+        return {
+            provider: 'github',
+            fields: [
+                {
+                    localField: 'title',
+                    externalField: 'title',
+                    direction: 'bidirectional',
+                },
+                {
+                    localField: 'descriptionRef',
+                    externalField: 'body',
+                    direction: 'bidirectional',
+                    toExternal: 'hydrateDescription',
+                    toLocal: 'createDescriptionDoc',
+                },
+                {
+                    localField: 'status',
+                    externalField: 'state',
+                    direction: 'bidirectional',
+                    toExternal: 'statusToGitHubState',
+                    toLocal: 'gitHubStateToStatus',
+                },
+                {
+                    localField: 'tags',
+                    externalField: 'labels',
+                    direction: 'bidirectional',
+                },
+                {
+                    localField: 'priority',
+                    externalField: 'labels',
+                    direction: 'bidirectional',
+                    toExternal: 'priorityToLabel',
+                    toLocal: 'labelToPriority',
+                },
+                {
+                    localField: 'taskType',
+                    externalField: 'labels',
+                    direction: 'bidirectional',
+                    toExternal: 'taskTypeToLabel',
+                    toLocal: 'labelToTaskType',
+                },
+                {
+                    localField: 'assignee',
+                    externalField: 'assignees',
+                    direction: 'bidirectional',
+                },
+            ],
+        };
+    }
+}
+/**
+ * Placeholder GitHub ExternalProvider.
+ *
+ * Used when the provider is registered in the registry before configuration.
+ * Connection testing always returns false. The task adapter throws on all operations.
+ */
+class GitHubPlaceholderProvider {
+    name = 'github';
+    displayName = 'GitHub';
+    supportedAdapters = ['task'];
+    taskAdapter = new GitHubPlaceholderTaskAdapter();
+    async testConnection(_config) {
+        return false;
+    }
+    getTaskAdapter() {
+        return this.taskAdapter;
+    }
+}
+// ============================================================================
+// Factory Functions
+// ============================================================================
+/**
+ * Create a configured GitHub provider.
+ *
+ * The provider is ready to use for sync operations when a valid
+ * token is provided in the config. The task adapter is initialized
+ * immediately with the provided credentials.
+ *
+ * @param config - Provider configuration with token and optional apiBaseUrl
+ * @returns A fully configured GitHub ExternalProvider
+ */
+export function createGitHubProvider(config) {
+    return new GitHubProvider(config);
+}
+/**
+ * Create a placeholder GitHub provider.
+ *
+ * The provider is registered by default in the provider registry so that
+ * the system knows GitHub is an available provider. Connection testing
+ * always returns false and all adapter methods throw until configured.
+ *
+ * @returns A placeholder GitHub ExternalProvider
+ */
+export function createGitHubPlaceholderProvider() {
+    return new GitHubPlaceholderProvider();
+}
+//# sourceMappingURL=github-provider.js.map

package/dist/external-sync/providers/github/github-provider.js.map

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

package/dist/external-sync/providers/github/github-task-adapter.d.ts

@@ -0,0 +1,135 @@
+/**
+ * GitHub Task Sync Adapter
+ *
+ * Implements TaskSyncAdapter for GitHub Issues.
+ * Uses GitHubApiClient internally for all API operations and maps between
+ * the normalized ExternalTask format and GitHub's issue representation.
+ *
+ * Project format: 'owner/repo' (e.g., 'stoneforge-ai/stoneforge')
+ * External ID format: issue number as string (e.g., '42')
+ */
+import type { TaskSyncAdapter, ExternalTask, ExternalTaskInput, TaskFieldMapConfig } from '@stoneforge/core';
+import type { Timestamp } from '@stoneforge/core';
+import type { GitHubApiClientOptions } from './github-api.js';
+/**
+ * Returns the default color for a given sf:* label name.
+ * Falls back to a neutral gray if no specific color is defined.
+ */
+export declare function getDefaultLabelColor(labelName: string): string;
+/**
+ * TaskSyncAdapter implementation for GitHub Issues.
+ *
+ * Maps between Stoneforge's normalized ExternalTask format and GitHub's
+ * issue API. Uses GitHubApiClient for all HTTP operations.
+ *
+ * Auto-creates sf:* labels on the target repository before assigning them
+ * to issues, preventing GitHub 422 "Validation Failed" errors.
+ *
+ * Usage:
+ * ```typescript
+ * const adapter = new GitHubTaskAdapter({
+ *   token: 'ghp_...',
+ *   apiBaseUrl: 'https://api.github.com', // optional
+ * });
+ *
+ * const issue = await adapter.getIssue('owner/repo', '42');
+ * const issues = await adapter.listIssuesSince('owner/repo', Date.now());
+ * ```
+ */
+export declare class GitHubTaskAdapter implements TaskSyncAdapter {
+    private readonly client;
+    /**
+     * Per-repo cache of known label names.
+     * Key is 'owner/repo', value is a Set of label names that exist on the repo.
+     * Populated once per repo per session to avoid redundant API calls.
+     */
+    private readonly labelCache;
+    constructor(options: GitHubApiClientOptions);
+    /**
+     * Fetch a single issue by its number.
+     *
+     * @param project - Repository in 'owner/repo' format
+     * @param externalId - GitHub issue number as a string
+     * @returns The normalized ExternalTask, or null if not found
+     */
+    getIssue(project: string, externalId: string): Promise<ExternalTask | null>;
+    /**
+     * List all issues updated since the given timestamp.
+     *
+     * Fetches all issues (open and closed) that have been updated since
+     * the provided timestamp. Uses auto-pagination to retrieve all matching
+     * issues across multiple pages.
+     *
+     * @param project - Repository in 'owner/repo' format
+     * @param since - Timestamp (milliseconds since epoch) to filter by
+     * @returns Array of normalized ExternalTask objects
+     */
+    listIssuesSince(project: string, since: Timestamp): Promise<ExternalTask[]>;
+    /**
+     * Create a new issue in the specified repository.
+     *
+     * Maps ExternalTaskInput fields to GitHub's create issue payload:
+     * - title -> title
+     * - body -> body
+     * - labels -> labels (as label names)
+     *
+     * Note: Assignees are intentionally NOT set on created issues. Stoneforge
+     * assignees are ephemeral agents that don't correspond to GitHub users.
+     *
+     * Note: The 'state' field from ExternalTaskInput is ignored for creation
+     * since GitHub issues are always created in the 'open' state.
+     *
+     * @param project - Repository in 'owner/repo' format
+     * @param issue - The issue data to create
+     * @returns The created ExternalTask with its new external ID and URL
+     */
+    createIssue(project: string, issue: ExternalTaskInput): Promise<ExternalTask>;
+    /**
+     * Update an existing issue in the specified repository.
+     *
+     * Maps partial ExternalTaskInput fields to GitHub's update issue payload.
+     * Only fields present in the updates object are sent to GitHub —
+     * undefined fields are left unchanged.
+     *
+     * @param project - Repository in 'owner/repo' format
+     * @param externalId - GitHub issue number as a string
+     * @param updates - Partial issue data to update
+     * @returns The updated ExternalTask
+     */
+    updateIssue(project: string, externalId: string, updates: Partial<ExternalTaskInput>): Promise<ExternalTask>;
+    /**
+     * Ensures that all sf:* labels in the given list exist on the target repository.
+     *
+     * For each label with the sync prefix (sf:), checks the per-repo cache first.
+     * If the cache hasn't been populated yet, fetches all labels from the repo once.
+     * Any missing sf:* labels are created with sensible default colors.
+     *
+     * Non-sf:* labels (user-managed) are not checked or created — those are the
+     * user's responsibility.
+     *
+     * @param project - Repository in 'owner/repo' format
+     * @param labels - Array of label names that will be assigned to an issue
+     */
+    ensureLabelsExist(project: string, labels: string[]): Promise<void>;
+    /**
+     * Returns the GitHub-specific field mapping configuration.
+     *
+     * This configuration is used by the shared task sync adapter utilities
+     * to map between Stoneforge task fields and GitHub issue fields.
+     *
+     * The returned TaskFieldMapConfig describes individual field mappings
+     * with their directions and transform function names.
+     *
+     * @returns TaskFieldMapConfig for GitHub
+     */
+    getFieldMapConfig(): TaskFieldMapConfig;
+}
+/**
+ * Returns the GitHub-specific TaskSyncFieldMapConfig for use with
+ * the shared task sync adapter utilities.
+ *
+ * This is a convenience export for code that needs the config directly
+ * without going through the adapter's getFieldMapConfig() method.
+ */
+export { GITHUB_FIELD_MAP_CONFIG } from './github-field-map.js';
+//# sourceMappingURL=github-task-adapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"github-task-adapter.d.ts","sourceRoot":"","sources":["../../../../src/external-sync/providers/github/github-task-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EACnB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD,OAAO,KAAK,EAAE,sBAAsB,EAAe,MAAM,iBAAiB,CAAC;AA6F3E;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE9D;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,iBAAkB,YAAW,eAAe;IACvD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IAEzC;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAuC;gBAEtD,OAAO,EAAE,sBAAsB;IAI3C;;;;;;OAMG;IACG,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAsBjF;;;;;;;;;;OAUG;IACG,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAejF;;;;;;;;;;;;;;;;;OAiBG;IACG,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,YAAY,CAAC;IAkBnF;;;;;;;;;;;OAWG;IACG,WAAW,CACf,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,OAAO,CAAC,iBAAiB,CAAC,GAClC,OAAO,CAAC,YAAY,CAAC;IAqCxB;;;;;;;;;;;;OAYG;IACG,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA8CzE;;;;;;;;;;OAUG;IACH,iBAAiB,IAAI,kBAAkB;CAkDxC;AAED;;;;;;GAMG;AACH,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC"}