/** * Format Preservation Sync Service (T-034B) * * Routes sync to comment-only mode for external items (preserves original format) * and full sync mode for internal items (allows title/description updates). * * Architecture: * - External US (origin=external): Comment-only sync (no title/description changes) * - Internal US (origin=internal): Full sync (title, description, status, comments) */ import { LivingDocsUSFile } from '../types/living-docs-us-file.js'; import { GitHubClientV2 } from '../../plugins/specweave/lib/integrations/github/github-client-v2.js'; import { JiraClient } from '../integrations/jira/jira-client.js'; import { AdoClient } from '../integrations/ado/ado-client.js'; import { Logger } from '../utils/logger.js'; export interface SyncConfig { /** Allow updating external items from SpecWeave (Internal → External) */ canUpdateExternalItems?: boolean; /** Allow upserting internal items from external tools (External → Internal) */ canUpsertInternalItems?: boolean; /** Allow status updates (both directions) */ canUpdateStatus?: boolean; } export interface TaskCompletionInfo { taskId: string; title: string; completed: boolean; } export interface ACCompletionInfo { acId: string; description: string; satisfied: boolean; } export interface CompletionCommentData { tasks: TaskCompletionInfo[]; acceptanceCriteria: ACCompletionInfo[]; progressPercentage: number; livingDocsUrl?: string; prUrl?: string; prBranch?: string; prNumber?: number; } export declare class FormatPreservationSyncService { private logger; private config; private projectRoot; constructor(config?: SyncConfig, options?: { logger?: Logger; projectRoot?: string; }); /** * Sync User Story to external tool with origin-based routing * * - External US (origin=external) → Comment-only sync * - Internal US (origin=internal) → Full sync */ syncUserStory(usFile: LivingDocsUSFile, completionData: CompletionCommentData, externalClient: GitHubClientV2 | JiraClient | AdoClient): Promise; /** * Sync External US (Comment-only mode) * * Preserves original title/description, only adds completion comments */ private syncExternalUS; /** * Post comment to external tool with idempotency check + atomic locking * * Handles GitHub, JIRA, and ADO with platform-specific logic. * Uses atomic locking to prevent TOCTOU race conditions. */ private postCommentWithIdempotency; /** * Post GitHub comment with atomic locking to prevent concurrent duplicates */ private postGitHubCommentWithIdempotency; /** * Update external tool status to target state * * @param usFile - User story file with external tool info * @param targetStatus - Target status name (e.g., "Done", "Closed") * @param externalClient - External tool client instance */ private updateExternalStatus; /** * Sync Internal US (Full sync mode) * * Allows updating title, description, status, and comments */ private syncInternalUS; /** * Build completion comment with task/AC progress * * Format: * ## Progress Update * * ### Completed Tasks * - ✅ [T-001] Task title * - ✅ [T-002] Another task * * ### Acceptance Criteria * - ✅ **AC-US1-01**: Criteria description * - ✅ **AC-US1-02**: Another criteria * * **Progress**: 8/11 tasks completed (73%) * * [View Living Docs](url) */ buildCompletionComment(data: CompletionCommentData): string; /** * Post JIRA comment with atomic locking to prevent concurrent duplicates * FIX: Prevent duplicate comments under concurrent load * * Note: JIRA doesn't have a simple getComments API exposed in our client, * so we rely on atomic locking to serialize comment posts per issue. */ private postJiraCommentWithIdempotency; /** * Post ADO comment with atomic locking to prevent concurrent duplicates * FIX: Prevent duplicate comments under concurrent load * * Note: ADO doesn't have a simple getComments API exposed in our client, * so we rely on atomic locking to serialize comment posts per work item. */ private postAdoCommentWithIdempotency; } //# sourceMappingURL=format-preservation-sync.d.ts.map