@stoneforge/quarry 1.12.0 → 1.13.0

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"}