@stoneforge/quarry 1.10.2 → 1.13.0

package/dist/cli/commands/external-sync.js

@@ -0,0 +1,1647 @@
+/**
+ * External Sync Commands - Manage bidirectional sync with external services
+ *
+ * Provides CLI commands for external service synchronization:
+ * - config: Show/set provider configuration (tokens, projects)
+ * - link: Link a task to an external issue
+ * - link-all: Bulk-link all unlinked tasks to external issues
+ * - unlink: Remove external link from a task
+ * - push: Push linked tasks to external service
+ * - pull: Pull changes from external for linked tasks
+ * - sync: Bidirectional sync (push + pull)
+ * - status: Show sync state overview
+ * - resolve: Resolve sync conflicts
+ */
+import { success, failure, ExitCode } from '../types.js';
+import { getOutputMode } from '../formatter.js';
+import { createAPI, resolveDatabasePath } from '../db.js';
+import { createStorage, initializeSchema } from '@stoneforge/storage';
+import { getValue, setValue, VALID_AUTO_LINK_PROVIDERS } from '../../config/index.js';
+import { taskToExternalTask, getFieldMapConfigForProvider } from '../../external-sync/adapters/task-sync-adapter.js';
+// ============================================================================
+// Settings Service Helper
+// ============================================================================
+/**
+ * Dynamically imports and creates a SettingsService from a storage backend.
+ * Uses optional peer dependency @stoneforge/smithy.
+ */
+async function createSettingsServiceFromOptions(options) {
+    const dbPath = resolveDatabasePath(options);
+    if (!dbPath) {
+        return {
+            settingsService: null,
+            error: 'No database found. Run "sf init" to initialize a workspace, or specify --db path',
+        };
+    }
+    try {
+        const backend = createStorage({ path: dbPath, create: true });
+        initializeSchema(backend);
+        // Dynamic import to handle optional peer dependency
+        const { createSettingsService } = await import('@stoneforge/smithy/services');
+        return { settingsService: createSettingsService(backend) };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        // If the import fails, the smithy package isn't available
+        if (message.includes('Cannot find') || message.includes('MODULE_NOT_FOUND')) {
+            return {
+                settingsService: null,
+                error: 'External sync requires @stoneforge/smithy package. Ensure it is installed.',
+            };
+        }
+        return {
+            settingsService: null,
+            error: `Failed to initialize settings: ${message}`,
+        };
+    }
+}
+// ============================================================================
+// Token Masking
+// ============================================================================
+/**
+ * Masks a token for display, showing only first 4 and last 4 characters
+ */
+function maskToken(token) {
+    if (token.length <= 8) {
+        return '****';
+    }
+    return `${token.slice(0, 4)}...${token.slice(-4)}`;
+}
+// ============================================================================
+// Config Command
+// ============================================================================
+async function configHandler(args, options) {
+    const { settingsService, error } = await createSettingsServiceFromOptions(options);
+    if (error) {
+        return failure(error, ExitCode.GENERAL_ERROR);
+    }
+    const settings = settingsService.getExternalSyncSettings();
+    const mode = getOutputMode(options);
+    // Also get file-based config for display
+    const enabled = getValue('externalSync.enabled');
+    const conflictStrategy = getValue('externalSync.conflictStrategy');
+    const defaultDirection = getValue('externalSync.defaultDirection');
+    const pollInterval = getValue('externalSync.pollInterval');
+    const autoLink = getValue('externalSync.autoLink');
+    const autoLinkProvider = getValue('externalSync.autoLinkProvider');
+    const configData = {
+        enabled,
+        conflictStrategy,
+        defaultDirection,
+        pollInterval,
+        autoLink,
+        autoLinkProvider,
+        providers: Object.fromEntries(Object.entries(settings.providers).map(([name, config]) => [
+            name,
+            {
+                ...config,
+                token: config.token ? maskToken(config.token) : undefined,
+            },
+        ])),
+    };
+    if (mode === 'json') {
+        return success(configData);
+    }
+    if (mode === 'quiet') {
+        const providerNames = Object.keys(settings.providers);
+        return success(providerNames.length > 0 ? providerNames.join(',') : 'none');
+    }
+    // Human-readable output
+    const lines = [
+        'External Sync Configuration',
+        '',
+        `  Enabled:            ${enabled ? 'yes' : 'no'}`,
+        `  Conflict strategy:  ${conflictStrategy}`,
+        `  Default direction:  ${defaultDirection}`,
+        `  Poll interval:      ${pollInterval}ms`,
+        `  Auto-link:          ${autoLink ? 'yes' : 'no'}`,
+        `  Auto-link provider: ${autoLinkProvider ?? '(not set)'}`,
+        '',
+    ];
+    const providerEntries = Object.entries(settings.providers);
+    if (providerEntries.length === 0) {
+        lines.push('  Providers:          (none configured)');
+        lines.push('');
+        lines.push('  Run "sf external-sync config set-token <provider> <token>" to configure a provider.');
+    }
+    else {
+        lines.push('  Providers:');
+        for (const [name, config] of providerEntries) {
+            lines.push(`    ${name}:`);
+            lines.push(`      Token:           ${config.token ? maskToken(config.token) : '(not set)'}`);
+            lines.push(`      API URL:         ${config.apiBaseUrl ?? '(default)'}`);
+            lines.push(`      Default project: ${config.defaultProject ?? '(not set)'}`);
+        }
+    }
+    return success(configData, lines.join('\n'));
+}
+// ============================================================================
+// Config Set-Token Command
+// ============================================================================
+async function configSetTokenHandler(args, options) {
+    if (args.length < 2) {
+        return failure('Usage: sf external-sync config set-token <provider> <token>', ExitCode.INVALID_ARGUMENTS);
+    }
+    const [provider, token] = args;
+    const { settingsService, error } = await createSettingsServiceFromOptions(options);
+    if (error) {
+        return failure(error, ExitCode.GENERAL_ERROR);
+    }
+    const existing = settingsService.getProviderConfig(provider) ?? { provider };
+    settingsService.setProviderConfig(provider, { ...existing, token });
+    const mode = getOutputMode(options);
+    if (mode === 'json') {
+        return success({ provider, tokenSet: true });
+    }
+    if (mode === 'quiet') {
+        return success(provider);
+    }
+    return success({ provider, tokenSet: true }, `Token set for provider "${provider}" (${maskToken(token)})`);
+}
+// ============================================================================
+// Config Set-Project Command
+// ============================================================================
+async function configSetProjectHandler(args, options) {
+    if (args.length < 2) {
+        return failure('Usage: sf external-sync config set-project <provider> <project>', ExitCode.INVALID_ARGUMENTS);
+    }
+    const [provider, project] = args;
+    const { settingsService, error } = await createSettingsServiceFromOptions(options);
+    if (error) {
+        return failure(error, ExitCode.GENERAL_ERROR);
+    }
+    const existing = settingsService.getProviderConfig(provider) ?? { provider };
+    settingsService.setProviderConfig(provider, { ...existing, defaultProject: project });
+    const mode = getOutputMode(options);
+    if (mode === 'json') {
+        return success({ provider, defaultProject: project });
+    }
+    if (mode === 'quiet') {
+        return success(project);
+    }
+    return success({ provider, defaultProject: project }, `Default project set for provider "${provider}": ${project}`);
+}
+// ============================================================================
+// Config Set-Auto-Link Command
+// ============================================================================
+async function configSetAutoLinkHandler(args, options) {
+    if (args.length < 1) {
+        return failure('Usage: sf external-sync config set-auto-link <provider>', ExitCode.INVALID_ARGUMENTS);
+    }
+    const [provider] = args;
+    // Validate provider name
+    if (!VALID_AUTO_LINK_PROVIDERS.includes(provider)) {
+        return failure(`Invalid provider "${provider}". Must be one of: ${VALID_AUTO_LINK_PROVIDERS.join(', ')}`, ExitCode.VALIDATION);
+    }
+    // Check if provider has a token configured
+    const { settingsService, error: settingsError } = await createSettingsServiceFromOptions(options);
+    let tokenWarning;
+    if (!settingsError) {
+        const providerConfig = settingsService.getProviderConfig(provider);
+        if (!providerConfig?.token) {
+            tokenWarning = `Warning: Provider "${provider}" has no token configured. Auto-link will not work until a token is set. Run "sf external-sync config set-token ${provider} <token>".`;
+        }
+    }
+    // Set both autoLink and autoLinkProvider
+    setValue('externalSync.autoLink', true);
+    setValue('externalSync.autoLinkProvider', provider);
+    const mode = getOutputMode(options);
+    if (mode === 'json') {
+        return success({ autoLink: true, autoLinkProvider: provider, warning: tokenWarning });
+    }
+    if (mode === 'quiet') {
+        return success(provider);
+    }
+    const lines = [`Auto-link enabled with provider "${provider}".`];
+    if (tokenWarning) {
+        lines.push('');
+        lines.push(tokenWarning);
+    }
+    return success({ autoLink: true, autoLinkProvider: provider }, lines.join('\n'));
+}
+// ============================================================================
+// Config Disable-Auto-Link Command
+// ============================================================================
+async function configDisableAutoLinkHandler(_args, options) {
+    // Set autoLink to false and clear autoLinkProvider
+    setValue('externalSync.autoLink', false);
+    setValue('externalSync.autoLinkProvider', undefined);
+    const mode = getOutputMode(options);
+    if (mode === 'json') {
+        return success({ autoLink: false, autoLinkProvider: null });
+    }
+    if (mode === 'quiet') {
+        return success('disabled');
+    }
+    return success({ autoLink: false }, 'Auto-link disabled.');
+}
+const linkOptions = [
+    {
+        name: 'provider',
+        short: 'p',
+        description: 'Provider name (default: github)',
+        hasValue: true,
+    },
+];
+async function linkHandler(args, options) {
+    if (args.length < 2) {
+        return failure('Usage: sf external-sync link <taskId> <url-or-issue-number>', ExitCode.INVALID_ARGUMENTS);
+    }
+    const [taskId, urlOrNumber] = args;
+    const provider = options.provider ?? 'github';
+    const { api, error } = createAPI(options);
+    if (error) {
+        return failure(error, ExitCode.GENERAL_ERROR);
+    }
+    // Resolve task
+    let task;
+    try {
+        task = await api.get(taskId);
+    }
+    catch {
+        return failure(`Task not found: ${taskId}`, ExitCode.NOT_FOUND);
+    }
+    if (!task) {
+        return failure(`Task not found: ${taskId}`, ExitCode.NOT_FOUND);
+    }
+    if (task.type !== 'task') {
+        return failure(`Element ${taskId} is not a task (type: ${task.type})`, ExitCode.VALIDATION);
+    }
+    // Determine the external URL
+    let externalUrl;
+    let externalId;
+    if (/^\d+$/.test(urlOrNumber)) {
+        // Bare number — construct URL from default project
+        const { settingsService, error: settingsError } = await createSettingsServiceFromOptions(options);
+        if (settingsError) {
+            return failure(settingsError, ExitCode.GENERAL_ERROR);
+        }
+        const providerConfig = settingsService.getProviderConfig(provider);
+        if (!providerConfig?.defaultProject) {
+            return failure(`No default project configured for provider "${provider}". ` +
+                `Run "sf external-sync config set-project ${provider} <owner/repo>" first, ` +
+                `or provide a full URL.`, ExitCode.VALIDATION);
+        }
+        externalId = urlOrNumber;
+        if (provider === 'github') {
+            const baseUrl = providerConfig.apiBaseUrl
+                ? providerConfig.apiBaseUrl.replace(/\/api\/v3\/?$/, '').replace(/\/$/, '')
+                : 'https://github.com';
+            externalUrl = `${baseUrl}/${providerConfig.defaultProject}/issues/${urlOrNumber}`;
+        }
+        else {
+            // Generic URL construction for other providers
+            externalUrl = `${providerConfig.defaultProject}#${urlOrNumber}`;
+        }
+    }
+    else {
+        // Full URL provided
+        externalUrl = urlOrNumber;
+        // Extract issue number from URL
+        const match = urlOrNumber.match(/\/(\d+)\/?$/);
+        externalId = match ? match[1] : urlOrNumber;
+    }
+    // Extract project from URL if possible
+    let project;
+    const ghMatch = externalUrl.match(/github\.com\/([^/]+\/[^/]+)\//);
+    if (ghMatch) {
+        project = ghMatch[1];
+    }
+    // Update task with externalRef and _externalSync metadata
+    const syncMetadata = {
+        provider,
+        project: project ?? '',
+        externalId,
+        url: externalUrl,
+        direction: getValue('externalSync.defaultDirection'),
+        adapterType: 'task',
+    };
+    try {
+        const existingMetadata = (task.metadata ?? {});
+        await api.update(taskId, {
+            externalRef: externalUrl,
+            metadata: {
+                ...existingMetadata,
+                _externalSync: syncMetadata,
+            },
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return failure(`Failed to update task: ${message}`, ExitCode.GENERAL_ERROR);
+    }
+    const mode = getOutputMode(options);
+    if (mode === 'json') {
+        return success({ taskId, externalUrl, provider, externalId, project });
+    }
+    if (mode === 'quiet') {
+        return success(externalUrl);
+    }
+    return success({ taskId, externalUrl, provider, externalId }, `Linked task ${taskId} to ${externalUrl}`);
+}
+// ============================================================================
+// Unlink Command
+// ============================================================================
+async function unlinkHandler(args, options) {
+    if (args.length < 1) {
+        return failure('Usage: sf external-sync unlink <taskId>', ExitCode.INVALID_ARGUMENTS);
+    }
+    const [taskId] = args;
+    const { api, error } = createAPI(options);
+    if (error) {
+        return failure(error, ExitCode.GENERAL_ERROR);
+    }
+    // Resolve task
+    let task;
+    try {
+        task = await api.get(taskId);
+    }
+    catch {
+        return failure(`Task not found: ${taskId}`, ExitCode.NOT_FOUND);
+    }
+    if (!task) {
+        return failure(`Task not found: ${taskId}`, ExitCode.NOT_FOUND);
+    }
+    if (task.type !== 'task') {
+        return failure(`Element ${taskId} is not a task (type: ${task.type})`, ExitCode.VALIDATION);
+    }
+    if (!task.externalRef) {
+        return failure(`Task ${taskId} is not linked to an external issue`, ExitCode.VALIDATION);
+    }
+    // Clear externalRef and _externalSync metadata
+    try {
+        const existingMetadata = (task.metadata ?? {});
+        const { _externalSync: _, ...restMetadata } = existingMetadata;
+        await api.update(taskId, {
+            externalRef: undefined,
+            metadata: restMetadata,
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return failure(`Failed to update task: ${message}`, ExitCode.GENERAL_ERROR);
+    }
+    const mode = getOutputMode(options);
+    if (mode === 'json') {
+        return success({ taskId, unlinked: true });
+    }
+    if (mode === 'quiet') {
+        return success(taskId);
+    }
+    return success({ taskId, unlinked: true }, `Unlinked task ${taskId} from external issue`);
+}
+const pushOptions = [
+    {
+        name: 'all',
+        short: 'a',
+        description: 'Push all linked tasks',
+    },
+    {
+        name: 'force',
+        short: 'f',
+        description: 'Push all linked tasks regardless of whether they have changed',
+    },
+];
+async function pushHandler(args, options) {
+    const { api, error } = createAPI(options);
+    if (error) {
+        return failure(error, ExitCode.GENERAL_ERROR);
+    }
+    // Get settings service to create a configured sync engine
+    const { settingsService, error: settingsError } = await createSettingsServiceFromOptions(options);
+    if (settingsError) {
+        return failure(settingsError, ExitCode.GENERAL_ERROR);
+    }
+    const syncSettings = settingsService.getExternalSyncSettings();
+    const providerConfigs = Object.values(syncSettings.providers).filter((p) => !!p.token);
+    if (providerConfigs.length === 0) {
+        return failure('No providers configured with tokens. Run "sf external-sync config set-token <provider> <token>" first.', ExitCode.GENERAL_ERROR);
+    }
+    // Build sync options
+    const { createSyncEngine, createConfiguredProviderRegistry } = await import('../../external-sync/index.js');
+    const registry = createConfiguredProviderRegistry(providerConfigs.map((p) => ({
+        provider: p.provider,
+        token: p.token,
+        apiBaseUrl: p.apiBaseUrl,
+        defaultProject: p.defaultProject,
+    })));
+    const engine = createSyncEngine({
+        api,
+        registry,
+        settings: settingsService,
+        providerConfigs: providerConfigs.map((p) => ({
+            provider: p.provider,
+            token: p.token,
+            apiBaseUrl: p.apiBaseUrl,
+            defaultProject: p.defaultProject,
+        })),
+    });
+    // Build push options
+    const syncPushOptions = {};
+    if (options.all) {
+        syncPushOptions.all = true;
+    }
+    else if (args.length > 0) {
+        syncPushOptions.taskIds = args;
+    }
+    else {
+        return failure('Usage: sf external-sync push [taskId...] or sf external-sync push --all', ExitCode.INVALID_ARGUMENTS);
+    }
+    if (options.force) {
+        syncPushOptions.force = true;
+    }
+    try {
+        const result = await engine.push(syncPushOptions);
+        const mode = getOutputMode(options);
+        const output = {
+            success: result.success,
+            pushed: result.pushed,
+            skipped: result.skipped,
+            errors: result.errors,
+            conflicts: result.conflicts,
+        };
+        if (mode === 'json') {
+            return success(output);
+        }
+        if (mode === 'quiet') {
+            return success(String(result.pushed));
+        }
+        const lines = [
+            `Push: ${result.pushed} task(s) pushed successfully`,
+            '',
+        ];
+        if (result.skipped > 0) {
+            lines.push(`Skipped: ${result.skipped}`);
+        }
+        if (result.errors.length > 0) {
+            lines.push('');
+            lines.push(`Errors (${result.errors.length}):`);
+            for (const err of result.errors) {
+                lines.push(`  ${err.elementId ?? 'unknown'}: ${err.message}`);
+            }
+        }
+        if (result.conflicts.length > 0) {
+            lines.push('');
+            lines.push(`Conflicts (${result.conflicts.length}):`);
+            for (const conflict of result.conflicts) {
+                lines.push(`  ${conflict.elementId} ↔ ${conflict.externalId} (${conflict.strategy}, resolved: ${conflict.resolved})`);
+            }
+        }
+        return success(output, lines.join('\n'));
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return failure(`Push failed: ${message}`, ExitCode.GENERAL_ERROR);
+    }
+}
+const pullOptions = [
+    {
+        name: 'provider',
+        short: 'p',
+        description: 'Provider to pull from (default: all configured)',
+        hasValue: true,
+    },
+    {
+        name: 'discover',
+        short: 'd',
+        description: 'Discover new issues not yet linked',
+    },
+];
+async function pullHandler(_args, options) {
+    const { api, error } = createAPI(options);
+    if (error) {
+        return failure(error, ExitCode.GENERAL_ERROR);
+    }
+    const { settingsService, error: settingsError } = await createSettingsServiceFromOptions(options);
+    if (settingsError) {
+        return failure(settingsError, ExitCode.GENERAL_ERROR);
+    }
+    const settings = settingsService.getExternalSyncSettings();
+    const providerNames = options.provider
+        ? [options.provider]
+        : Object.keys(settings.providers);
+    if (providerNames.length === 0) {
+        return failure('No providers configured. Run "sf external-sync config set-token <provider> <token>" first.', ExitCode.VALIDATION);
+    }
+    // Validate providers have tokens and build provider configs
+    const providerConfigs = [];
+    const invalidProviders = [];
+    for (const name of providerNames) {
+        const config = settings.providers[name];
+        if (config?.token) {
+            providerConfigs.push({
+                provider: config.provider,
+                token: config.token,
+                apiBaseUrl: config.apiBaseUrl,
+                defaultProject: config.defaultProject,
+            });
+        }
+        else {
+            invalidProviders.push(name);
+        }
+    }
+    if (providerConfigs.length === 0) {
+        return failure('No providers with valid tokens found. Run "sf external-sync config set-token <provider> <token>" first.', ExitCode.GENERAL_ERROR);
+    }
+    // Create sync engine (same pattern as pushHandler)
+    const { createSyncEngine, createConfiguredProviderRegistry } = await import('../../external-sync/index.js');
+    const registry = createConfiguredProviderRegistry(providerConfigs.map((p) => ({
+        provider: p.provider,
+        token: p.token,
+        apiBaseUrl: p.apiBaseUrl,
+        defaultProject: p.defaultProject,
+    })));
+    const engine = createSyncEngine({
+        api,
+        registry,
+        settings: settingsService,
+        providerConfigs: providerConfigs.map((p) => ({
+            provider: p.provider,
+            token: p.token,
+            apiBaseUrl: p.apiBaseUrl,
+            defaultProject: p.defaultProject,
+        })),
+    });
+    // Build pull options — discover maps to 'all' to create local tasks for unlinked external issues
+    const syncPullOptions = {};
+    if (options.discover) {
+        syncPullOptions.all = true;
+    }
+    try {
+        const result = await engine.pull(syncPullOptions);
+        const mode = getOutputMode(options);
+        const output = {
+            success: result.success,
+            pulled: result.pulled,
+            skipped: result.skipped,
+            errors: result.errors,
+            conflicts: result.conflicts,
+            invalidProviders,
+        };
+        if (mode === 'json') {
+            return success(output);
+        }
+        if (mode === 'quiet') {
+            return success(String(result.pulled));
+        }
+        const lines = [
+            `Pull: ${result.pulled} task(s) pulled successfully`,
+            '',
+        ];
+        if (result.skipped > 0) {
+            lines.push(`Skipped: ${result.skipped}`);
+        }
+        if (invalidProviders.length > 0) {
+            lines.push('');
+            lines.push(`Skipped providers (no token): ${invalidProviders.join(', ')}`);
+        }
+        if (result.errors.length > 0) {
+            lines.push('');
+            lines.push(`Errors (${result.errors.length}):`);
+            for (const err of result.errors) {
+                lines.push(`  ${err.elementId ?? 'unknown'}: ${err.message}`);
+            }
+        }
+        if (result.conflicts.length > 0) {
+            lines.push('');
+            lines.push(`Conflicts (${result.conflicts.length}):`);
+            for (const conflict of result.conflicts) {
+                lines.push(`  ${conflict.elementId} ↔ ${conflict.externalId} (${conflict.strategy}, resolved: ${conflict.resolved})`);
+            }
+        }
+        return success(output, lines.join('\n'));
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return failure(`Pull failed: ${message}`, ExitCode.GENERAL_ERROR);
+    }
+}
+const syncOptions = [
+    {
+        name: 'dry-run',
+        short: 'n',
+        description: 'Show what would change without making changes',
+    },
+];
+async function syncHandler(_args, options) {
+    const { api, error: apiError } = createAPI(options);
+    if (apiError) {
+        return failure(apiError, ExitCode.GENERAL_ERROR);
+    }
+    const { settingsService, error: settingsError } = await createSettingsServiceFromOptions(options);
+    if (settingsError) {
+        return failure(settingsError, ExitCode.GENERAL_ERROR);
+    }
+    const syncSettings = settingsService.getExternalSyncSettings();
+    const isDryRun = options['dry-run'] ?? false;
+    const providerConfigs = Object.values(syncSettings.providers).filter((p) => !!p.token);
+    if (providerConfigs.length === 0) {
+        return failure('No providers configured with tokens. Run "sf external-sync config set-token <provider> <token>" first.', ExitCode.GENERAL_ERROR);
+    }
+    // Create sync engine (same pattern as pushHandler)
+    const { createSyncEngine, createConfiguredProviderRegistry } = await import('../../external-sync/index.js');
+    const registry = createConfiguredProviderRegistry(providerConfigs.map((p) => ({
+        provider: p.provider,
+        token: p.token,
+        apiBaseUrl: p.apiBaseUrl,
+        defaultProject: p.defaultProject,
+    })));
+    const engine = createSyncEngine({
+        api,
+        registry,
+        settings: settingsService,
+        providerConfigs: providerConfigs.map((p) => ({
+            provider: p.provider,
+            token: p.token,
+            apiBaseUrl: p.apiBaseUrl,
+            defaultProject: p.defaultProject,
+        })),
+    });
+    // Build sync options
+    const syncOpts = {};
+    if (isDryRun) {
+        syncOpts.dryRun = true;
+    }
+    try {
+        const result = await engine.sync(syncOpts);
+        const mode = getOutputMode(options);
+        const output = {
+            success: result.success,
+            dryRun: isDryRun,
+            pushed: result.pushed,
+            pulled: result.pulled,
+            skipped: result.skipped,
+            errors: result.errors,
+            conflicts: result.conflicts,
+        };
+        if (mode === 'json') {
+            return success(output);
+        }
+        if (mode === 'quiet') {
+            return success(`${result.pushed}/${result.pulled}`);
+        }
+        const lines = [
+            isDryRun ? 'Sync (dry run) - showing what would change' : 'Bidirectional Sync Complete',
+            '',
+            `  Pushed: ${result.pushed} task(s)`,
+            `  Pulled: ${result.pulled} task(s)`,
+        ];
+        if (result.skipped > 0) {
+            lines.push(`  Skipped: ${result.skipped} (no changes)`);
+        }
+        if (result.errors.length > 0) {
+            lines.push('');
+            lines.push(`Errors (${result.errors.length}):`);
+            for (const err of result.errors) {
+                lines.push(`  ${err.elementId ?? 'unknown'}: ${err.message}`);
+            }
+        }
+        if (result.conflicts.length > 0) {
+            lines.push('');
+            lines.push(`Conflicts (${result.conflicts.length}):`);
+            for (const conflict of result.conflicts) {
+                lines.push(`  ${conflict.elementId} ↔ ${conflict.externalId} (${conflict.strategy}, resolved: ${conflict.resolved})`);
+            }
+        }
+        return success(output, lines.join('\n'));
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return failure(`Sync failed: ${message}`, ExitCode.GENERAL_ERROR);
+    }
+}
+// ============================================================================
+// Status Command
+// ============================================================================
+async function statusHandler(_args, options) {
+    const { settingsService, error: settingsError } = await createSettingsServiceFromOptions(options);
+    if (settingsError) {
+        return failure(settingsError, ExitCode.GENERAL_ERROR);
+    }
+    const { api, error: apiError } = createAPI(options);
+    if (apiError) {
+        return failure(apiError, ExitCode.GENERAL_ERROR);
+    }
+    const settings = settingsService.getExternalSyncSettings();
+    const enabled = getValue('externalSync.enabled');
+    // Count linked tasks and check for conflicts
+    let linkedCount = 0;
+    let conflictCount = 0;
+    const providerCounts = {};
+    try {
+        const allTasks = await api.list({ type: 'task' });
+        for (const t of allTasks) {
+            const task = t;
+            if (task.externalRef && task.metadata?._externalSync) {
+                linkedCount++;
+                const syncMeta = task.metadata._externalSync;
+                const provider = syncMeta?.provider ?? 'unknown';
+                providerCounts[provider] = (providerCounts[provider] ?? 0) + 1;
+            }
+            if (task.tags?.includes('sync-conflict')) {
+                conflictCount++;
+            }
+        }
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return failure(`Failed to list tasks: ${message}`, ExitCode.GENERAL_ERROR);
+    }
+    // Build cursor info
+    const cursors = {};
+    for (const [key, value] of Object.entries(settings.syncCursors)) {
+        cursors[key] = value;
+    }
+    const mode = getOutputMode(options);
+    const statusData = {
+        enabled,
+        linkedTaskCount: linkedCount,
+        conflictCount,
+        providerCounts,
+        configuredProviders: Object.keys(settings.providers),
+        syncCursors: cursors,
+        pollIntervalMs: settings.pollIntervalMs,
+        defaultDirection: settings.defaultDirection,
+    };
+    if (mode === 'json') {
+        return success(statusData);
+    }
+    if (mode === 'quiet') {
+        return success(`${linkedCount}:${conflictCount}`);
+    }
+    const lines = [
+        'External Sync Status',
+        '',
+        `  Enabled:             ${enabled ? 'yes' : 'no'}`,
+        `  Linked tasks:        ${linkedCount}`,
+        `  Pending conflicts:   ${conflictCount}`,
+        `  Poll interval:       ${settings.pollIntervalMs}ms`,
+        `  Default direction:   ${settings.defaultDirection}`,
+        '',
+    ];
+    // Provider breakdown
+    const providerEntries = Object.entries(settings.providers);
+    if (providerEntries.length > 0) {
+        lines.push('  Providers:');
+        for (const [name, config] of providerEntries) {
+            const count = providerCounts[name] ?? 0;
+            const hasToken = config.token ? 'yes' : 'no';
+            lines.push(`    ${name}: ${count} linked task(s), token: ${hasToken}, project: ${config.defaultProject ?? '(not set)'}`);
+        }
+    }
+    else {
+        lines.push('  Providers: (none configured)');
+    }
+    // Sync cursors
+    const cursorEntries = Object.entries(cursors);
+    if (cursorEntries.length > 0) {
+        lines.push('');
+        lines.push('  Last sync cursors:');
+        for (const [key, value] of cursorEntries) {
+            lines.push(`    ${key}: ${value}`);
+        }
+    }
+    if (conflictCount > 0) {
+        lines.push('');
+        lines.push(`  ⚠ ${conflictCount} conflict(s) need resolution. Run "sf external-sync resolve <taskId> --keep local|remote".`);
+    }
+    return success(statusData, lines.join('\n'));
+}
+const resolveOptions = [
+    {
+        name: 'keep',
+        short: 'k',
+        description: 'Which version to keep: local or remote',
+        hasValue: true,
+        required: true,
+    },
+];
+async function resolveHandler(args, options) {
+    if (args.length < 1) {
+        return failure('Usage: sf external-sync resolve <taskId> --keep local|remote', ExitCode.INVALID_ARGUMENTS);
+    }
+    const [taskId] = args;
+    const keep = options.keep;
+    if (!keep || (keep !== 'local' && keep !== 'remote')) {
+        return failure('The --keep flag is required and must be either "local" or "remote"', ExitCode.INVALID_ARGUMENTS);
+    }
+    const { api, error } = createAPI(options);
+    if (error) {
+        return failure(error, ExitCode.GENERAL_ERROR);
+    }
+    // Resolve task
+    let task;
+    try {
+        task = await api.get(taskId);
+    }
+    catch {
+        return failure(`Task not found: ${taskId}`, ExitCode.NOT_FOUND);
+    }
+    if (!task) {
+        return failure(`Task not found: ${taskId}`, ExitCode.NOT_FOUND);
+    }
+    if (task.type !== 'task') {
+        return failure(`Element ${taskId} is not a task (type: ${task.type})`, ExitCode.VALIDATION);
+    }
+    if (!task.tags?.includes('sync-conflict')) {
+        return failure(`Task ${taskId} does not have a sync conflict. Only tasks tagged with "sync-conflict" can be resolved.`, ExitCode.VALIDATION);
+    }
+    // Remove sync-conflict tag and update metadata
+    try {
+        const newTags = (task.tags ?? []).filter((t) => t !== 'sync-conflict');
+        const existingMetadata = (task.metadata ?? {});
+        const syncMeta = (existingMetadata._externalSync ?? {});
+        // Record resolution in metadata
+        const updatedSyncMeta = {
+            ...syncMeta,
+            lastConflictResolution: {
+                resolvedAt: new Date().toISOString(),
+                kept: keep,
+            },
+        };
+        // Clear conflict data from metadata
+        const { _syncConflict: _, ...restMetadata } = existingMetadata;
+        await api.update(taskId, {
+            tags: newTags,
+            metadata: {
+                ...restMetadata,
+                _externalSync: updatedSyncMeta,
+            },
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return failure(`Failed to resolve conflict: ${message}`, ExitCode.GENERAL_ERROR);
+    }
+    const mode = getOutputMode(options);
+    if (mode === 'json') {
+        return success({ taskId, resolved: true, kept: keep });
+    }
+    if (mode === 'quiet') {
+        return success(taskId);
+    }
+    return success({ taskId, resolved: true, kept: keep }, `Resolved sync conflict for task ${taskId} (kept: ${keep})`);
+}
+const linkAllOptions = [
+    {
+        name: 'provider',
+        short: 'p',
+        description: 'Provider to link to (required)',
+        hasValue: true,
+        required: true,
+    },
+    {
+        name: 'project',
+        description: 'Override the default project',
+        hasValue: true,
+    },
+    {
+        name: 'status',
+        short: 's',
+        description: 'Only link tasks with this status (can be repeated)',
+        hasValue: true,
+        array: true,
+    },
+    {
+        name: 'dry-run',
+        short: 'n',
+        description: 'List tasks that would be linked without creating external issues',
+    },
+    {
+        name: 'batch-size',
+        short: 'b',
+        description: 'How many tasks to process concurrently (default: 10)',
+        hasValue: true,
+        defaultValue: '10',
+    },
+    {
+        name: 'force',
+        short: 'f',
+        description: 'Re-link tasks that are already linked to a different provider',
+    },
+];
+/**
+ * Helper to detect rate limit errors from GitHub or Linear providers.
+ * Returns the reset timestamp (epoch seconds) if available, or undefined.
+ */
+function isRateLimitError(err) {
+    // Try GitHub error shape
+    if (err &&
+        typeof err === 'object' &&
+        'isRateLimited' in err &&
+        err.isRateLimited) {
+        const rateLimit = err.rateLimit;
+        return { isRateLimit: true, resetAt: rateLimit?.reset };
+    }
+    // Also check error message for rate limit keywords
+    if (err instanceof Error && /rate.limit/i.test(err.message)) {
+        return { isRateLimit: true };
+    }
+    return { isRateLimit: false };
+}
+/**
+ * Extracts validation error details from a GitHub API error response.
+ * GitHub's 422 responses include an `errors` array with `resource`, `field`,
+ * `code`, and sometimes `value` or `message` entries.
+ *
+ * Example output: "invalid label: sf:priority:high"
+ */
+function extractValidationDetail(err) {
+    if (!err || typeof err !== 'object')
+        return null;
+    const responseBody = err.responseBody;
+    if (!responseBody || !Array.isArray(responseBody.errors))
+        return null;
+    const details = responseBody.errors
+        .map((e) => {
+        const parts = [];
+        if (e.code && typeof e.code === 'string')
+            parts.push(e.code);
+        if (e.field && typeof e.field === 'string')
+            parts.push(e.field);
+        if (e.value !== undefined)
+            parts.push(String(e.value));
+        if (e.message && typeof e.message === 'string')
+            parts.push(e.message);
+        return parts.join(': ');
+    })
+        .filter(Boolean);
+    return details.length > 0 ? details.join('; ') : null;
+}
+/**
+ * Creates an ExternalProvider instance from settings for the given provider name.
+ * Returns the provider, project, and direction, or an error message.
+ */
+async function createProviderFromSettings(providerName, projectOverride, options) {
+    const dbPath = resolveDatabasePath(options);
+    if (!dbPath) {
+        return { error: 'No database found. Run "sf init" to initialize a workspace, or specify --db path' };
+    }
+    try {
+        const backend = createStorage({ path: dbPath, create: true });
+        initializeSchema(backend);
+        // Dynamic import to handle optional peer dependency
+        const { createSettingsService } = await import('@stoneforge/smithy/services');
+        const settingsService = createSettingsService(backend);
+        const providerConfig = settingsService.getProviderConfig(providerName);
+        if (!providerConfig?.token) {
+            return { error: `Provider "${providerName}" has no token configured. Run "sf external-sync config set-token ${providerName} <token>" first.` };
+        }
+        const project = projectOverride ?? providerConfig.defaultProject;
+        if (!project) {
+            return { error: `No project specified and provider "${providerName}" has no default project configured. Use --project or run "sf external-sync config set-project ${providerName} <project>" first.` };
+        }
+        let provider;
+        if (providerName === 'github') {
+            const { createGitHubProvider } = await import('../../external-sync/providers/github/index.js');
+            provider = createGitHubProvider({
+                provider: 'github',
+                token: providerConfig.token,
+                apiBaseUrl: providerConfig.apiBaseUrl,
+                defaultProject: project,
+            });
+        }
+        else if (providerName === 'linear') {
+            const { createLinearProvider } = await import('../../external-sync/providers/linear/index.js');
+            provider = createLinearProvider({
+                apiKey: providerConfig.token,
+            });
+        }
+        else {
+            return { error: `Unsupported provider: "${providerName}". Supported providers: github, linear` };
+        }
+        const direction = (getValue('externalSync.defaultDirection') ?? 'bidirectional');
+        return { provider, project, direction };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (message.includes('Cannot find') || message.includes('MODULE_NOT_FOUND')) {
+            return { error: 'External sync requires @stoneforge/smithy package. Ensure it is installed.' };
+        }
+        return { error: `Failed to initialize provider: ${message}` };
+    }
+}
+/**
+ * Process a batch of tasks: create external issues and link them.
+ * Uses the adapter's field mapping to include priority, taskType, and status
+ * labels on the created external issues.
+ */
+async function processBatch(tasks, adapter, api, providerName, project, direction, progressLines) {
+    let succeeded = 0;
+    let failed = 0;
+    let rateLimited = false;
+    let resetAt;
+    const fieldMapConfig = getFieldMapConfigForProvider(providerName);
+    for (const task of tasks) {
+        try {
+            // Build the complete external task input using field mapping.
+            // This maps priority → sf:priority:* labels, taskType → sf:type:* labels,
+            // status → open/closed state, user tags → labels, and hydrates description.
+            const externalInput = await taskToExternalTask(task, fieldMapConfig, api);
+            // Create the external issue with fully mapped fields
+            const externalTask = await adapter.createIssue(project, externalInput);
+            // Build the ExternalSyncState metadata
+            const syncState = {
+                provider: providerName,
+                project,
+                externalId: externalTask.externalId,
+                url: externalTask.url,
+                direction,
+                adapterType: 'task',
+            };
+            // Update the task with externalRef and _externalSync metadata
+            const existingMetadata = (task.metadata ?? {});
+            await api.update(task.id, {
+                externalRef: externalTask.url,
+                metadata: {
+                    ...existingMetadata,
+                    _externalSync: syncState,
+                },
+            });
+            progressLines.push(`Linked ${task.id} → ${externalTask.url}`);
+            succeeded++;
+        }
+        catch (err) {
+            // Check for rate limit errors
+            const rlCheck = isRateLimitError(err);
+            if (rlCheck.isRateLimit) {
+                rateLimited = true;
+                resetAt = rlCheck.resetAt;
+                const message = err instanceof Error ? err.message : String(err);
+                progressLines.push(`Rate limit hit while linking ${task.id}: ${message}`);
+                // Stop processing further tasks in this batch
+                break;
+            }
+            // Log warning and continue with next task
+            const message = err instanceof Error ? err.message : String(err);
+            const detail = extractValidationDetail(err);
+            progressLines.push(detail
+                ? `Failed to link ${task.id}: ${message} — ${detail}`
+                : `Failed to link ${task.id}: ${message}`);
+            failed++;
+        }
+    }
+    return { succeeded, failed, rateLimited, resetAt };
+}
+async function linkAllHandler(_args, options) {
+    const providerName = options.provider;
+    if (!providerName) {
+        return failure('The --provider flag is required. Usage: sf external-sync link-all --provider <provider>', ExitCode.INVALID_ARGUMENTS);
+    }
+    const isDryRun = options['dry-run'] ?? false;
+    const force = options.force ?? false;
+    const batchSize = parseInt(options['batch-size'] ?? '10', 10);
+    if (isNaN(batchSize) || batchSize < 1) {
+        return failure('--batch-size must be a positive integer', ExitCode.INVALID_ARGUMENTS);
+    }
+    // Parse status filters
+    const statusFilters = [];
+    if (options.status) {
+        if (Array.isArray(options.status)) {
+            statusFilters.push(...options.status);
+        }
+        else {
+            statusFilters.push(options.status);
+        }
+    }
+    // Get API for querying/updating tasks
+    const { api, error: apiError } = createAPI(options);
+    if (apiError) {
+        return failure(apiError, ExitCode.GENERAL_ERROR);
+    }
+    // Query all tasks
+    let allTasks;
+    try {
+        const results = await api.list({ type: 'task' });
+        allTasks = results;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return failure(`Failed to list tasks: ${message}`, ExitCode.GENERAL_ERROR);
+    }
+    // Filter tasks: unlinked tasks, plus (with --force) tasks linked to a DIFFERENT provider
+    let relinkedFromProvider;
+    let relinkCount = 0;
+    let tasksToLink = allTasks.filter((task) => {
+        const metadata = (task.metadata ?? {});
+        const syncState = metadata._externalSync;
+        if (!syncState) {
+            // Unlinked task — always include
+            return true;
+        }
+        if (force && syncState.provider !== providerName) {
+            // Force mode: include tasks linked to a DIFFERENT provider
+            relinkedFromProvider = syncState.provider;
+            relinkCount++;
+            return true;
+        }
+        // Already linked (to same provider, or force not set) — skip
+        return false;
+    });
+    // Apply status filter if specified
+    if (statusFilters.length > 0) {
+        tasksToLink = tasksToLink.filter((task) => statusFilters.includes(task.status));
+    }
+    // Skip tombstone tasks by default (soft-deleted)
+    tasksToLink = tasksToLink.filter((task) => task.status !== 'tombstone');
+    const mode = getOutputMode(options);
+    if (tasksToLink.length === 0) {
+        const result = { linked: 0, failed: 0, skipped: 0, total: 0, dryRun: isDryRun };
+        if (mode === 'json') {
+            return success(result);
+        }
+        const hint = force
+            ? 'No tasks found to re-link matching the specified criteria.'
+            : 'No unlinked tasks found. Use --force to re-link tasks from a different provider.';
+        return success(result, hint);
+    }
+    // Dry run — just list tasks that would be linked
+    if (isDryRun) {
+        const taskList = tasksToLink.map((t) => ({
+            id: t.id,
+            title: t.title,
+            status: t.status,
+        }));
+        const jsonResult = {
+            dryRun: true,
+            provider: providerName,
+            total: tasksToLink.length,
+            tasks: taskList,
+        };
+        if (force && relinkCount > 0) {
+            jsonResult.force = true;
+            jsonResult.relinkCount = relinkCount;
+            jsonResult.relinkFromProvider = relinkedFromProvider;
+        }
+        if (mode === 'json') {
+            return success(jsonResult);
+        }
+        if (mode === 'quiet') {
+            return success(String(tasksToLink.length));
+        }
+        const lines = [];
+        if (force && relinkCount > 0) {
+            lines.push(`Dry run: Re-linking ${relinkCount} task(s) from ${relinkedFromProvider} to ${providerName} (--force)`);
+            const newCount = tasksToLink.length - relinkCount;
+            if (newCount > 0) {
+                lines.push(`  Plus ${newCount} unlinked task(s) to link`);
+            }
+        }
+        else {
+            lines.push(`Dry run: ${tasksToLink.length} task(s) would be linked to ${providerName}`);
+        }
+        lines.push('');
+        for (const task of tasksToLink) {
+            lines.push(`  ${task.id}  ${task.status.padEnd(12)} ${task.title}`);
+        }
+        return success(jsonResult, lines.join('\n'));
+    }
+    // Create provider for actual linking (supports DI for testing)
+    const providerFactory = options._providerFactory ?? createProviderFromSettings;
+    const { provider: externalProvider, project, direction, error: providerError, } = await providerFactory(providerName, options.project, options);
+    if (providerError) {
+        return failure(providerError, ExitCode.GENERAL_ERROR);
+    }
+    // Get the task adapter
+    const adapter = externalProvider.getTaskAdapter?.();
+    if (!adapter) {
+        return failure(`Provider "${providerName}" does not support task sync`, ExitCode.GENERAL_ERROR);
+    }
+    const progressLines = [];
+    // Log re-linking info when using --force
+    if (force && relinkCount > 0 && mode !== 'json' && mode !== 'quiet') {
+        progressLines.push(`Re-linking ${relinkCount} task(s) from ${relinkedFromProvider} to ${providerName} (--force)`);
+        const newCount = tasksToLink.length - relinkCount;
+        if (newCount > 0) {
+            progressLines.push(`Linking ${newCount} unlinked task(s)`);
+        }
+        progressLines.push('');
+    }
+    // Process tasks in batches
+    let totalSucceeded = 0;
+    let totalFailed = 0;
+    let rateLimited = false;
+    let rateLimitResetAt;
+    for (let i = 0; i < tasksToLink.length; i += batchSize) {
+        const batch = tasksToLink.slice(i, i + batchSize);
+        const batchResult = await processBatch(batch, adapter, api, providerName, project, direction, progressLines);
+        totalSucceeded += batchResult.succeeded;
+        totalFailed += batchResult.failed;
+        if (batchResult.rateLimited) {
+            rateLimited = true;
+            rateLimitResetAt = batchResult.resetAt;
+            break;
+        }
+        // Small delay between batches to be gentle on the API
+        if (i + batchSize < tasksToLink.length) {
+            await new Promise((resolve) => setTimeout(resolve, 100));
+        }
+    }
+    const skipped = tasksToLink.length - totalSucceeded - totalFailed;
+    // Build result
+    const result = {
+        provider: providerName,
+        project,
+        linked: totalSucceeded,
+        failed: totalFailed,
+        skipped,
+        total: tasksToLink.length,
+        rateLimited,
+        rateLimitResetAt: rateLimitResetAt ? new Date(rateLimitResetAt * 1000).toISOString() : undefined,
+    };
+    if (force && relinkCount > 0) {
+        result.force = true;
+        result.relinkCount = relinkCount;
+        result.relinkFromProvider = relinkedFromProvider;
+    }
+    if (mode === 'json') {
+        return success(result);
+    }
+    if (mode === 'quiet') {
+        return success(String(totalSucceeded));
+    }
+    // Human-readable output
+    const lines = [...progressLines, ''];
+    // Summary
+    const summaryParts = [`Linked ${totalSucceeded} tasks to ${providerName}`];
+    if (totalFailed > 0) {
+        summaryParts.push(`(${totalFailed} failed)`);
+    }
+    if (skipped > 0) {
+        summaryParts.push(`(${skipped} skipped)`);
+    }
+    lines.push(summaryParts.join(' '));
+    if (rateLimited) {
+        lines.push('');
+        if (rateLimitResetAt) {
+            const resetDate = new Date(rateLimitResetAt * 1000);
+            lines.push(`Rate limit reached. Resets at ${resetDate.toISOString()}. Re-run this command after the reset to link remaining tasks.`);
+        }
+        else {
+            lines.push('Rate limit reached. Re-run this command later to link remaining tasks.');
+        }
+    }
+    return success(result, lines.join('\n'));
+}
+// ============================================================================
+// Config Parent Command (for subcommand structure)
+// ============================================================================
+const configSetTokenCommand = {
+    name: 'set-token',
+    description: 'Set authentication token for a provider',
+    usage: 'sf external-sync config set-token <provider> <token>',
+    help: `Store an authentication token for an external sync provider.
+
+The token is stored in the local SQLite database (not git-tracked).
+
+Arguments:
+  provider    Provider name (e.g., github, linear)
+  token       Authentication token
+
+Examples:
+  sf external-sync config set-token github ghp_xxxxxxxxxxxx
+  sf external-sync config set-token linear lin_api_xxxxxxxxxxxx`,
+    options: [],
+    handler: configSetTokenHandler,
+};
+const configSetProjectCommand = {
+    name: 'set-project',
+    description: 'Set default project for a provider',
+    usage: 'sf external-sync config set-project <provider> <project>',
+    help: `Set the default project (e.g., owner/repo) for an external sync provider.
+
+This is used when linking tasks with bare issue numbers.
+
+Arguments:
+  provider    Provider name (e.g., github, linear)
+  project     Project identifier (e.g., owner/repo for GitHub)
+
+Examples:
+  sf external-sync config set-project github my-org/my-repo
+  sf external-sync config set-project linear MY-PROJECT`,
+    options: [],
+    handler: configSetProjectHandler,
+};
+const configSetAutoLinkCommand = {
+    name: 'set-auto-link',
+    description: 'Enable auto-link with a provider',
+    usage: 'sf external-sync config set-auto-link <provider>',
+    help: `Enable auto-link for new tasks with the specified provider.
+
+When auto-link is enabled, newly created Stoneforge tasks will automatically
+get a corresponding external issue created and linked.
+
+Arguments:
+  provider    Provider name (github or linear)
+
+Examples:
+  sf external-sync config set-auto-link github
+  sf external-sync config set-auto-link linear`,
+    options: [],
+    handler: configSetAutoLinkHandler,
+};
+const configDisableAutoLinkCommand = {
+    name: 'disable-auto-link',
+    description: 'Disable auto-link',
+    usage: 'sf external-sync config disable-auto-link',
+    help: `Disable auto-link for new tasks.
+
+Clears the auto-link provider and disables automatic external issue creation.
+
+Examples:
+  sf external-sync config disable-auto-link`,
+    options: [],
+    handler: configDisableAutoLinkHandler,
+};
+const configParentCommand = {
+    name: 'config',
+    description: 'Show or set provider configuration',
+    usage: 'sf external-sync config [set-token|set-project|set-auto-link|disable-auto-link]',
+    help: `Show current external sync provider configuration.
+
+Tokens are masked in output for security.
+
+Subcommands:
+  set-token <provider> <token>     Store auth token
+  set-project <provider> <project> Set default project
+  set-auto-link <provider>         Enable auto-link with a provider
+  disable-auto-link                Disable auto-link
+
+Examples:
+  sf external-sync config
+  sf external-sync config set-token github ghp_xxxxxxxxxxxx
+  sf external-sync config set-project github my-org/my-repo
+  sf external-sync config set-auto-link github
+  sf external-sync config disable-auto-link`,
+    subcommands: {
+        'set-token': configSetTokenCommand,
+        'set-project': configSetProjectCommand,
+        'set-auto-link': configSetAutoLinkCommand,
+        'disable-auto-link': configDisableAutoLinkCommand,
+    },
+    options: [],
+    handler: configHandler,
+};
+// ============================================================================
+// Link Parent Command
+// ============================================================================
+const linkCommand = {
+    name: 'link',
+    description: 'Link a task to an external issue',
+    usage: 'sf external-sync link <taskId> <url-or-issue-number>',
+    help: `Link a Stoneforge task to an external issue (e.g., GitHub issue).
+
+Sets the task's externalRef and _externalSync metadata. If given a bare
+issue number, constructs the URL from the provider's default project.
+
+Arguments:
+  taskId           Stoneforge task ID
+  url-or-number    Full URL or bare issue number
+
+Options:
+  -p, --provider   Provider name (default: github)
+
+Examples:
+  sf external-sync link el-abc123 https://github.com/org/repo/issues/42
+  sf external-sync link el-abc123 42
+  sf external-sync link el-abc123 42 --provider github`,
+    options: linkOptions,
+    handler: linkHandler,
+};
+// ============================================================================
+// Link-All Command
+// ============================================================================
+const linkAllCommand = {
+    name: 'link-all',
+    description: 'Bulk-link all unlinked tasks to external issues',
+    usage: 'sf external-sync link-all --provider <provider> [--project <project>] [--status <status>] [--dry-run] [--batch-size <n>] [--force]',
+    help: `Create external issues for all unlinked tasks and link them in bulk.
+
+Finds all tasks that do NOT have external sync metadata and creates
+a corresponding external issue for each one, then links them.
+
+Use --force to re-link tasks that are already linked to a different provider.
+Tasks linked to the same target provider are always skipped.
+
+Options:
+  -p, --provider <name>    Provider to link to (required)
+      --project <project>  Override the default project
+  -s, --status <status>    Only link tasks with this status (can be repeated)
+  -n, --dry-run            List tasks that would be linked without creating issues
+  -b, --batch-size <n>     Tasks to process concurrently (default: 10)
+  -f, --force              Re-link tasks already linked to a different provider
+
+Rate Limits:
+  If a rate limit is hit, the command stops gracefully and reports how
+  many tasks were linked. Re-run the command to continue linking.
+
+Examples:
+  sf external-sync link-all --provider github
+  sf external-sync link-all --provider github --status open
+  sf external-sync link-all --provider github --status open --status in_progress
+  sf external-sync link-all --provider github --dry-run
+  sf external-sync link-all --provider github --project my-org/my-repo
+  sf external-sync link-all --provider linear --batch-size 5
+  sf external-sync link-all --provider linear --force
+  sf external-sync link-all --provider linear --force --dry-run`,
+    options: linkAllOptions,
+    handler: linkAllHandler,
+};
+// ============================================================================
+// Unlink Command
+// ============================================================================
+const unlinkCommand = {
+    name: 'unlink',
+    description: 'Remove external link from a task',
+    usage: 'sf external-sync unlink <taskId>',
+    help: `Remove the external link from a Stoneforge task.
+
+Clears the task's externalRef field and _externalSync metadata.
+
+Arguments:
+  taskId    Stoneforge task ID
+
+Examples:
+  sf external-sync unlink el-abc123`,
+    options: [],
+    handler: unlinkHandler,
+};
+// ============================================================================
+// Push Command
+// ============================================================================
+const pushCommand = {
+    name: 'push',
+    description: 'Push linked tasks to external service',
+    usage: 'sf external-sync push [taskId...] [--all] [--force]',
+    help: `Push specific linked tasks to their external service, or push all linked tasks.
+
+If specific task IDs are given, pushes only those tasks. With --all,
+pushes every task that has an external link.
+
+Use --force to push all linked tasks regardless of whether their local
+content has changed. This is useful when label generation logic changes
+and the external representation needs to be refreshed.
+
+Arguments:
+  taskId...        One or more task IDs to push (optional with --all)
+
+Options:
+  -a, --all        Push all linked tasks
+  -f, --force      Push all linked tasks regardless of whether they have changed
+
+Examples:
+  sf external-sync push el-abc123
+  sf external-sync push el-abc123 el-def456
+  sf external-sync push --all
+  sf external-sync push --all --force
+  sf external-sync push el-abc123 --force`,
+    options: pushOptions,
+    handler: pushHandler,
+};
+// ============================================================================
+// Pull Command
+// ============================================================================
+const pullCommand = {
+    name: 'pull',
+    description: 'Pull changes from external for linked tasks',
+    usage: 'sf external-sync pull [--provider <name>] [--discover]',
+    help: `Pull changes from external services for all linked tasks.
+
+Optionally discover new issues not yet linked to Stoneforge tasks.
+
+Options:
+  -p, --provider <name>   Pull from specific provider (default: all configured)
+  -d, --discover          Discover new unlinked issues
+
+Examples:
+  sf external-sync pull
+  sf external-sync pull --provider github
+  sf external-sync pull --discover`,
+    options: pullOptions,
+    handler: pullHandler,
+};
+// ============================================================================
+// Sync Command
+// ============================================================================
+const biSyncCommand = {
+    name: 'sync',
+    description: 'Bidirectional sync with external services',
+    usage: 'sf external-sync sync [--dry-run]',
+    help: `Run bidirectional sync between Stoneforge and external services.
+
+Performs both push and pull operations. In dry-run mode, reports what
+would change without making any modifications.
+
+Options:
+  -n, --dry-run    Show what would change without making changes
+
+Examples:
+  sf external-sync sync
+  sf external-sync sync --dry-run`,
+    options: syncOptions,
+    handler: syncHandler,
+};
+// ============================================================================
+// Status Command
+// ============================================================================
+const extStatusCommand = {
+    name: 'status',
+    description: 'Show external sync state',
+    usage: 'sf external-sync status',
+    help: `Show the current external sync state.
+
+Displays linked task count, last sync times, configured providers,
+and pending conflicts.
+
+Examples:
+  sf external-sync status
+  sf external-sync status --json`,
+    options: [],
+    handler: statusHandler,
+};
+// ============================================================================
+// Resolve Command
+// ============================================================================
+const resolveCommand = {
+    name: 'resolve',
+    description: 'Resolve a sync conflict',
+    usage: 'sf external-sync resolve <taskId> --keep local|remote',
+    help: `Resolve a sync conflict by choosing which version to keep.
+
+Tasks with sync conflicts are tagged with "sync-conflict". This command
+resolves the conflict by keeping either the local or remote version.
+
+Arguments:
+  taskId    Task ID with a sync conflict
+
+Options:
+  -k, --keep <version>   Which version to keep: local or remote (required)
+
+Examples:
+  sf external-sync resolve el-abc123 --keep local
+  sf external-sync resolve el-abc123 --keep remote`,
+    options: resolveOptions,
+    handler: resolveHandler,
+};
+// ============================================================================
+// External Sync Parent Command
+// ============================================================================
+export const externalSyncCommand = {
+    name: 'external-sync',
+    description: 'External service sync commands',
+    usage: 'sf external-sync <command> [options]',
+    help: `Manage bidirectional synchronization between Stoneforge and external services
+(GitHub Issues, Linear, etc.).
+
+Commands:
+  config                              Show provider configuration
+  config set-token <provider> <token> Store auth token
+  config set-project <provider> <project> Set default project
+  config set-auto-link <provider>     Enable auto-link with a provider
+  config disable-auto-link            Disable auto-link
+  link <taskId> <url-or-issue-number> Link task to external issue
+  link-all --provider <name>          Bulk-link all unlinked tasks
+  unlink <taskId>                     Remove external link
+  push [taskId...] [--force]           Push linked task(s) to external
+  pull                                Pull changes from external
+  sync [--dry-run]                    Bidirectional sync
+  status                              Show sync state
+  resolve <taskId> --keep local|remote Resolve sync conflict
+
+Examples:
+  sf external-sync config
+  sf external-sync config set-token github ghp_xxxxxxxxxxxx
+  sf external-sync config set-project github my-org/my-repo
+  sf external-sync config set-auto-link github
+  sf external-sync config disable-auto-link
+  sf external-sync link el-abc123 42
+  sf external-sync link-all --provider github
+  sf external-sync link-all --provider github --dry-run
+  sf external-sync push --all
+  sf external-sync push --all --force
+  sf external-sync pull
+  sf external-sync sync --dry-run
+  sf external-sync status
+  sf external-sync resolve el-abc123 --keep local`,
+    subcommands: {
+        config: configParentCommand,
+        link: linkCommand,
+        'link-all': linkAllCommand,
+        unlink: unlinkCommand,
+        push: pushCommand,
+        pull: pullCommand,
+        sync: biSyncCommand,
+        status: extStatusCommand,
+        resolve: resolveCommand,
+    },
+    handler: async (_args, options) => {
+        const mode = getOutputMode(options);
+        if (mode === 'json') {
+            return success({
+                commands: ['config', 'link', 'link-all', 'unlink', 'push', 'pull', 'sync', 'status', 'resolve'],
+            });
+        }
+        return failure('Usage: sf external-sync <command>\n\nCommands: config, link, link-all, unlink, push, pull, sync, status, resolve\n\nRun "sf external-sync --help" for more information.', ExitCode.INVALID_ARGUMENTS);
+    },
+};
+//# sourceMappingURL=external-sync.js.map