@shepai/cli 1.155.0-pr481.af47b59 → 1.155.0-pr482.ac79b36

package/dist/packages/core/src/infrastructure/services/notifications/notification.service.js

@@ -5,6 +5,7 @@
  * events to enabled channels:
  * - Notification bus (for SSE → in-app toasts and browser notifications)
  * - Desktop notifier (node-notifier for OS-level notifications)
+ * - Telegram bot (sends messages via Bot API)
  *
  * Channel enable/disable and event type filters are read from Settings.
  */
@@ -23,12 +24,27 @@ const EVENT_TYPE_TO_CONFIG_KEY = {
     [NotificationEventType.PrBlocked]: 'prBlocked',
     [NotificationEventType.MergeReviewReady]: 'mergeReviewReady',
 };
+const EVENT_TYPE_TO_TELEGRAM_KEY = {
+    [NotificationEventType.AgentStarted]: 'agentStarted',
+    [NotificationEventType.PhaseCompleted]: 'phaseCompleted',
+    [NotificationEventType.WaitingApproval]: 'waitingApproval',
+    [NotificationEventType.AgentCompleted]: 'agentCompleted',
+    [NotificationEventType.AgentFailed]: 'agentFailed',
+    [NotificationEventType.PrMerged]: 'prMerged',
+    [NotificationEventType.PrClosed]: 'prClosed',
+    [NotificationEventType.PrChecksPassed]: 'prChecksPassed',
+    [NotificationEventType.PrChecksFailed]: 'prChecksFailed',
+    [NotificationEventType.PrBlocked]: 'prBlocked',
+    [NotificationEventType.MergeReviewReady]: 'mergeReviewReady',
+};
 export class NotificationService {
     bus;
     desktopNotifier;
-    constructor(bus, desktopNotifier) {
+    telegramService;
+    constructor(bus, desktopNotifier, telegramService) {
         this.bus = bus;
         this.desktopNotifier = desktopNotifier;
+        this.telegramService = telegramService;
     }
     notify(event) {
         const { notifications } = getSettings();
@@ -43,5 +59,28 @@ export class NotificationService {
         }
         // Desktop notifications disabled — removed in favour of in-app toasts.
         // The DesktopNotifier dependency is kept for API compatibility but never called.
+        // Send to Telegram if enabled and event type is allowed
+        this.sendTelegramNotification(event);
+    }
+    /**
+     * Send a notification to Telegram if the channel is enabled and
+     * the specific event type is allowed in the Telegram notify events config.
+     */
+    sendTelegramNotification(event) {
+        const { telegram } = getSettings();
+        if (!telegram?.enabled || !telegram.botToken || !telegram.chatId) {
+            return;
+        }
+        // Check Telegram-specific event type filter
+        const telegramKey = EVENT_TYPE_TO_TELEGRAM_KEY[event.eventType];
+        if (telegramKey && !telegram.notifyEvents[telegramKey]) {
+            return;
+        }
+        // Fire-and-forget: don't block the notification pipeline on Telegram API calls
+        this.telegramService.sendNotification(telegram.botToken, telegram.chatId, event).catch(() => {
+            // Swallow errors silently — Telegram is a best-effort channel.
+            // Network failures, rate limits, or invalid tokens should not
+            // break the core notification flow.
+        });
     }
 }

package/dist/packages/core/src/infrastructure/services/telegram/telegram.service.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Telegram Service Implementation
+ *
+ * Implements the ITelegramService port using the Telegram Bot HTTP API.
+ * Uses native `fetch` (available in Node 18+) — no external SDK required.
+ *
+ * All methods are stateless; bot token and chat ID are passed as parameters
+ * so the service can be used for validation before persisting config.
+ */
+import type { NotificationEvent } from '../../../domain/generated/output.js';
+import type { ITelegramService, TelegramBotInfo, TelegramChatResolution } from '../../../application/ports/output/services/telegram-service.interface.js';
+export declare class TelegramService implements ITelegramService {
+    validateBotToken(botToken: string): Promise<TelegramBotInfo>;
+    resolveChatId(botToken: string): Promise<TelegramChatResolution>;
+    sendMessage(botToken: string, chatId: string, text: string): Promise<void>;
+    sendNotification(botToken: string, chatId: string, event: NotificationEvent): Promise<void>;
+    /**
+     * Escape HTML special characters for Telegram's HTML parse mode.
+     */
+    private escapeHtml;
+}
+//# sourceMappingURL=telegram.service.d.ts.map

package/dist/packages/core/src/infrastructure/services/telegram/telegram.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telegram.service.d.ts","sourceRoot":"","sources":["../../../../../../../packages/core/src/infrastructure/services/telegram/telegram.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AAE7E,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EACf,sBAAsB,EACvB,MAAM,0EAA0E,CAAC;AA2ClF,qBAAa,eAAgB,YAAW,gBAAgB;IAChD,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IA6B5D,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC;IA0ChE,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA8B1E,gBAAgB,CACpB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,iBAAiB,GACvB,OAAO,CAAC,IAAI,CAAC;IAgBhB;;OAEG;IACH,OAAO,CAAC,UAAU;CAGnB"}

package/dist/packages/core/src/infrastructure/services/telegram/telegram.service.js

@@ -0,0 +1,128 @@
+/**
+ * Telegram Service Implementation
+ *
+ * Implements the ITelegramService port using the Telegram Bot HTTP API.
+ * Uses native `fetch` (available in Node 18+) — no external SDK required.
+ *
+ * All methods are stateless; bot token and chat ID are passed as parameters
+ * so the service can be used for validation before persisting config.
+ */
+import { NotificationEventType } from '../../../domain/generated/output.js';
+import { TelegramAuthError, TelegramNoChatError, TelegramSendError, } from '../../../application/ports/output/services/telegram-service.interface.js';
+const TELEGRAM_API_BASE = 'https://api.telegram.org/bot';
+/**
+ * Human-readable labels for notification event types.
+ */
+const EVENT_LABELS = {
+    [NotificationEventType.AgentStarted]: 'Agent Started',
+    [NotificationEventType.PhaseCompleted]: 'Phase Completed',
+    [NotificationEventType.WaitingApproval]: 'Waiting for Approval',
+    [NotificationEventType.AgentCompleted]: 'Agent Completed',
+    [NotificationEventType.AgentFailed]: 'Agent Failed',
+    [NotificationEventType.PrMerged]: 'PR Merged',
+    [NotificationEventType.PrClosed]: 'PR Closed',
+    [NotificationEventType.PrChecksPassed]: 'PR Checks Passed',
+    [NotificationEventType.PrChecksFailed]: 'PR Checks Failed',
+    [NotificationEventType.PrBlocked]: 'PR Blocked',
+    [NotificationEventType.MergeReviewReady]: 'Merge Review Ready',
+};
+/**
+ * Emoji indicators for notification event types.
+ */
+const EVENT_EMOJI = {
+    [NotificationEventType.AgentStarted]: '\u{1F680}',
+    [NotificationEventType.PhaseCompleted]: '\u2705',
+    [NotificationEventType.WaitingApproval]: '\u23F3',
+    [NotificationEventType.AgentCompleted]: '\u{1F389}',
+    [NotificationEventType.AgentFailed]: '\u274C',
+    [NotificationEventType.PrMerged]: '\u{1F7E2}',
+    [NotificationEventType.PrClosed]: '\u{1F534}',
+    [NotificationEventType.PrChecksPassed]: '\u2705',
+    [NotificationEventType.PrChecksFailed]: '\u274C',
+    [NotificationEventType.PrBlocked]: '\u26A0\uFE0F',
+    [NotificationEventType.MergeReviewReady]: '\u{1F4CB}',
+};
+export class TelegramService {
+    async validateBotToken(botToken) {
+        const url = `${TELEGRAM_API_BASE}${botToken}/getMe`;
+        let response;
+        try {
+            response = await fetch(url);
+        }
+        catch (error) {
+            throw new TelegramAuthError(`Failed to connect to Telegram API: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const body = (await response.json());
+        if (!body.ok || !body.result) {
+            throw new TelegramAuthError(body.description ?? 'Invalid bot token');
+        }
+        return {
+            id: body.result.id,
+            firstName: body.result.first_name,
+            username: body.result.username,
+        };
+    }
+    async resolveChatId(botToken) {
+        const url = `${TELEGRAM_API_BASE}${botToken}/getUpdates?limit=10&allowed_updates=["message"]`;
+        let response;
+        try {
+            response = await fetch(url);
+        }
+        catch (error) {
+            throw new TelegramNoChatError(`Failed to connect to Telegram API: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const body = (await response.json());
+        if (!body.ok || !body.result) {
+            throw new TelegramNoChatError('Failed to fetch bot updates');
+        }
+        // Look for a /start message
+        const startUpdate = body.result.find((update) => update.message?.text === '/start');
+        if (!startUpdate?.message) {
+            throw new TelegramNoChatError('No /start message found. Please send /start to your bot on Telegram first, then retry.');
+        }
+        return {
+            chatId: String(startUpdate.message.chat.id),
+            firstName: startUpdate.message.from?.first_name ?? 'Unknown',
+        };
+    }
+    async sendMessage(botToken, chatId, text) {
+        const url = `${TELEGRAM_API_BASE}${botToken}/sendMessage`;
+        let response;
+        try {
+            response = await fetch(url, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    chat_id: chatId,
+                    text,
+                    parse_mode: 'HTML',
+                }),
+            });
+        }
+        catch (error) {
+            throw new TelegramSendError(`Failed to send Telegram message: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const body = (await response.json());
+        if (!body.ok) {
+            throw new TelegramSendError(`Telegram API error: ${body.description ?? 'Unknown error'}`);
+        }
+    }
+    async sendNotification(botToken, chatId, event) {
+        const emoji = EVENT_EMOJI[event.eventType] ?? '';
+        const label = EVENT_LABELS[event.eventType] ?? event.eventType;
+        const lines = [
+            `${emoji} <b>${label}</b>`,
+            `Feature: ${this.escapeHtml(event.featureName)}`,
+        ];
+        if (event.message) {
+            lines.push(`\n${this.escapeHtml(event.message)}`);
+        }
+        await this.sendMessage(botToken, chatId, lines.join('\n'));
+    }
+    /**
+     * Escape HTML special characters for Telegram's HTML parse mode.
+     */
+    escapeHtml(text) {
+        return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+    }
+}

package/dist/src/presentation/cli/commands/settings/index.d.ts

@@ -12,6 +12,7 @@
  *   shep settings ide       # Configure preferred IDE
  *   shep settings workflow  # Configure workflow defaults
  *   shep settings model     # Configure default LLM model
+ *   shep settings telegram  # Configure Telegram remote control
  */
 import { Command } from 'commander';
 /**

package/dist/src/presentation/cli/commands/settings/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../src/presentation/cli/commands/settings/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAUpC;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,OAAO,CAsB/C"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../src/presentation/cli/commands/settings/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAWpC;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,OAAO,CAuB/C"}

package/dist/src/presentation/cli/commands/settings/index.js

@@ -12,6 +12,7 @@
  *   shep settings ide       # Configure preferred IDE
  *   shep settings workflow  # Configure workflow defaults
  *   shep settings model     # Configure default LLM model
+ *   shep settings telegram  # Configure Telegram remote control
  */
 import { Command } from 'commander';
 import { createShowCommand } from './show.command.js';
@@ -20,6 +21,7 @@ import { createAgentCommand } from './agent.command.js';
 import { createIdeCommand } from './ide.command.js';
 import { createWorkflowCommand } from './workflow.command.js';
 import { createModelCommand } from './model.command.js';
+import { createTelegramCommand } from './telegram.command.js';
 import { onboardingWizard } from '../../../tui/wizards/onboarding/onboarding.wizard.js';
 import { messages } from '../../ui/index.js';
 /**
@@ -33,7 +35,8 @@ export function createSettingsCommand() {
         .addCommand(createAgentCommand())
         .addCommand(createIdeCommand())
         .addCommand(createWorkflowCommand())
-        .addCommand(createModelCommand());
+        .addCommand(createModelCommand())
+        .addCommand(createTelegramCommand());
     // Default action: launch the full setup wizard when no subcommand is given
     cmd.action(async () => {
         try {

package/dist/src/presentation/cli/commands/settings/telegram.command.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Telegram Configuration Command
+ *
+ * Configures the Telegram Bot integration for remote control and notifications.
+ *
+ * Usage:
+ *   shep settings telegram                                   # Interactive setup
+ *   shep settings telegram --bot-token <token>               # Set token + auto-pair
+ *   shep settings telegram --bot-token <token> --chat-id 123 # Set token + explicit chat
+ *   shep settings telegram --disable                          # Disable Telegram
+ *   shep settings telegram --status                           # Show current status
+ */
+import { Command } from 'commander';
+/**
+ * Create the Telegram configuration command.
+ */
+export declare function createTelegramCommand(): Command;
+//# sourceMappingURL=telegram.command.d.ts.map

package/dist/src/presentation/cli/commands/settings/telegram.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telegram.command.d.ts","sourceRoot":"","sources":["../../../../../../src/presentation/cli/commands/settings/telegram.command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAmBpC;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,OAAO,CAsD/C"}

package/dist/src/presentation/cli/commands/settings/telegram.command.js

@@ -0,0 +1,158 @@
+/**
+ * Telegram Configuration Command
+ *
+ * Configures the Telegram Bot integration for remote control and notifications.
+ *
+ * Usage:
+ *   shep settings telegram                                   # Interactive setup
+ *   shep settings telegram --bot-token <token>               # Set token + auto-pair
+ *   shep settings telegram --bot-token <token> --chat-id 123 # Set token + explicit chat
+ *   shep settings telegram --disable                          # Disable Telegram
+ *   shep settings telegram --status                           # Show current status
+ */
+import { Command } from 'commander';
+import { input, confirm } from '@inquirer/prompts';
+import { container } from '../../../../../packages/core/src/infrastructure/di/container.js';
+import { ConfigureTelegramUseCase } from '../../../../../packages/core/src/application/use-cases/telegram/configure-telegram.use-case.js';
+import { getSettings, resetSettings, initializeSettings, } from '../../../../../packages/core/src/infrastructure/services/settings.service.js';
+import { messages, colors, fmt, symbols } from '../../ui/index.js';
+/**
+ * Create the Telegram configuration command.
+ */
+export function createTelegramCommand() {
+    return new Command('telegram')
+        .description('Configure Telegram remote control and notifications')
+        .option('--bot-token <token>', 'Bot API token from @BotFather')
+        .option('--chat-id <id>', 'Telegram chat ID (auto-resolved if omitted)')
+        .option('--disable', 'Disable Telegram integration')
+        .option('--status', 'Show current Telegram configuration status')
+        .addHelpText('after', `
+Examples:
+  $ shep settings telegram                                   Interactive setup wizard
+  $ shep settings telegram --bot-token 123456:ABC-DEF...     Set token and auto-pair
+  $ shep settings telegram --disable                          Disable Telegram
+  $ shep settings telegram --status                           Show current status
+
+Setup guide:
+  1. Open Telegram and search for @BotFather
+  2. Send /newbot and follow the prompts to create a bot
+  3. Copy the bot token (looks like 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11)
+  4. Start a chat with your new bot and send /start
+  5. Run: shep settings telegram --bot-token <your-token>`)
+        .action(async (options) => {
+        try {
+            if (options.status) {
+                showTelegramStatus();
+                return;
+            }
+            if (options.disable) {
+                await disableTelegram();
+                return;
+            }
+            const hasFlags = options.botToken !== undefined;
+            if (hasFlags) {
+                await enableTelegramNonInteractive(options);
+            }
+            else {
+                await enableTelegramInteractive();
+            }
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            if (err.message.includes('force closed') || err.message.includes('User force closed')) {
+                messages.info('Configuration cancelled.');
+                return;
+            }
+            messages.error('Failed to configure Telegram', err);
+            process.exitCode = 1;
+        }
+    });
+}
+function showTelegramStatus() {
+    const settings = getSettings();
+    const telegram = settings.telegram;
+    if (!telegram?.enabled) {
+        messages.info('Telegram integration is disabled.');
+        return;
+    }
+    console.log(`\n${symbols.success} Telegram integration is ${colors.success('enabled')}`);
+    console.log(`  Bot token: ${colors.muted(telegram.botToken ? `****${telegram.botToken.slice(-8)}` : 'not set')}`);
+    console.log(`  Chat ID:   ${colors.muted(telegram.chatId ?? 'not set')}`);
+    const enabledEvents = Object.entries(telegram.notifyEvents)
+        .filter(([, enabled]) => enabled)
+        .map(([key]) => key);
+    console.log(`  Events:    ${colors.muted(enabledEvents.length > 0 ? enabledEvents.join(', ') : 'none')}\n`);
+}
+async function disableTelegram() {
+    const useCase = container.resolve(ConfigureTelegramUseCase);
+    const result = await useCase.execute({ enabled: false });
+    resetSettings();
+    initializeSettings(result.settings);
+    messages.success('Telegram integration disabled.');
+}
+async function enableTelegramNonInteractive(options) {
+    if (!options.botToken) {
+        messages.error('--bot-token is required when enabling Telegram.');
+        process.exitCode = 1;
+        return;
+    }
+    const useCase = container.resolve(ConfigureTelegramUseCase);
+    messages.info('Validating bot token...');
+    const result = await useCase.execute({
+        enabled: true,
+        botToken: options.botToken,
+        chatId: options.chatId,
+    });
+    resetSettings();
+    initializeSettings(result.settings);
+    if (result.botInfo) {
+        messages.success(`Connected to @${result.botInfo.username}`);
+    }
+    if (result.chatResolution) {
+        messages.success(`Paired with ${result.chatResolution.firstName} (chat ID: ${result.chatResolution.chatId})`);
+    }
+    messages.success('Telegram integration enabled. Check your Telegram for a confirmation message.');
+}
+async function enableTelegramInteractive() {
+    console.log(`\n${fmt.heading('Telegram Remote Control Setup')}\n`);
+    console.log(`${colors.muted('This wizard will connect Shep to your personal Telegram bot.')}`);
+    console.log(`${colors.muted('You will receive notifications and can send commands via Telegram.\n')}`);
+    console.log(`${colors.muted('Prerequisites:')}`);
+    console.log(`${colors.muted('  1. Create a bot via @BotFather on Telegram')}`);
+    console.log(`${colors.muted('  2. Send /start to your new bot')}\n`);
+    const botToken = await input({
+        message: 'Enter your bot token from @BotFather:',
+        validate: (value) => {
+            if (!value.trim())
+                return 'Bot token is required';
+            if (!value.includes(':'))
+                return 'Invalid bot token format (should contain ":")';
+            return true;
+        },
+    });
+    const useCase = container.resolve(ConfigureTelegramUseCase);
+    messages.info('Validating bot token...');
+    const result = await useCase.execute({
+        enabled: true,
+        botToken: botToken.trim(),
+    });
+    resetSettings();
+    initializeSettings(result.settings);
+    if (result.botInfo) {
+        messages.success(`Connected to @${result.botInfo.username}`);
+    }
+    if (result.chatResolution) {
+        messages.success(`Paired with ${result.chatResolution.firstName} (chat ID: ${result.chatResolution.chatId})`);
+    }
+    messages.success('Telegram integration enabled! Check your Telegram for a confirmation message.');
+    const wantTest = await confirm({
+        message: 'Send a test notification?',
+        default: false,
+    });
+    if (wantTest) {
+        const telegramSvc = container.resolve('ITelegramService');
+        const telegram = result.settings.telegram;
+        await telegramSvc.sendMessage(telegram.botToken, telegram.chatId, '\u{1F6CE}\uFE0F <b>Test notification from Shep!</b>\nIf you see this, everything is working.');
+        messages.success('Test notification sent!');
+    }
+}