@phuetz/code-buddy 1.1.0 → 1.3.0

package/dist/channels/gateway-lifecycle.js

@@ -0,0 +1,219 @@
+/**
+ * Gateway Lifecycle Manager
+ *
+ * Unified lifecycle management (start/stop/restart/status) for the
+ * messaging gateway subsystem. Tracks which channel adapters are
+ * currently active and provides per-channel readiness information.
+ */
+import { EventEmitter } from 'events';
+import { getChannelManager } from './core.js';
+import { logger } from '../utils/logger.js';
+// ============================================================================
+// Gateway Lifecycle Manager
+// ============================================================================
+/**
+ * Manages the lifecycle of the messaging gateway and its channel adapters.
+ *
+ * Wraps the existing ChannelManager with explicit start/stop/restart/status
+ * semantics for individual channels and the entire gateway.
+ */
+export class GatewayLifecycleManager extends EventEmitter {
+    manager;
+    activeChannels = new Set();
+    channelErrors = new Map();
+    constructor(manager) {
+        super();
+        this.manager = manager ?? getChannelManager();
+    }
+    /**
+     * Get the underlying ChannelManager.
+     */
+    getManager() {
+        return this.manager;
+    }
+    /**
+     * Start a single channel adapter by its channel type.
+     *
+     * The channel must already be registered with the ChannelManager.
+     * This calls connect() on the adapter and marks it as active.
+     *
+     * @param channelId - The channel type to start
+     * @throws Error if the channel is not registered
+     */
+    async start(channelId) {
+        const channel = this.manager.getChannel(channelId);
+        if (!channel) {
+            throw new Error(`Channel '${channelId}' is not registered`);
+        }
+        try {
+            await channel.connect();
+            this.activeChannels.add(channelId);
+            this.channelErrors.delete(channelId);
+            this.emit('channel:started', channelId);
+            logger.debug('Gateway: channel started', { channelId });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            this.channelErrors.set(channelId, message);
+            this.emit('channel:error', channelId, err instanceof Error ? err : new Error(message));
+            throw err;
+        }
+    }
+    /**
+     * Stop a single channel adapter by its channel type.
+     *
+     * Calls disconnect() on the adapter and removes it from the active set.
+     *
+     * @param channelId - The channel type to stop
+     * @throws Error if the channel is not registered
+     */
+    async stop(channelId) {
+        const channel = this.manager.getChannel(channelId);
+        if (!channel) {
+            throw new Error(`Channel '${channelId}' is not registered`);
+        }
+        try {
+            await channel.disconnect();
+        }
+        catch (err) {
+            logger.debug('Gateway: error during channel disconnect', {
+                channelId,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+        this.activeChannels.delete(channelId);
+        this.channelErrors.delete(channelId);
+        this.emit('channel:stopped', channelId);
+        logger.debug('Gateway: channel stopped', { channelId });
+    }
+    /**
+     * Restart a single channel adapter (stop + start).
+     *
+     * @param channelId - The channel type to restart
+     */
+    async restart(channelId) {
+        if (this.activeChannels.has(channelId)) {
+            await this.stop(channelId);
+        }
+        await this.start(channelId);
+    }
+    /**
+     * Start all registered channel adapters.
+     */
+    async startAll() {
+        const channels = this.manager.getAllChannels();
+        const errors = [];
+        for (const channel of channels) {
+            try {
+                await this.start(channel.type);
+            }
+            catch (err) {
+                errors.push({
+                    channelId: channel.type,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        this.emit('gateway:started');
+        if (errors.length > 0) {
+            logger.debug('Gateway: some channels failed to start', { errors });
+        }
+    }
+    /**
+     * Stop all active channel adapters.
+     */
+    async stopAll() {
+        const activeIds = [...this.activeChannels];
+        for (const channelId of activeIds) {
+            try {
+                await this.stop(channelId);
+            }
+            catch (err) {
+                logger.debug('Gateway: error stopping channel', {
+                    channelId,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        this.emit('gateway:stopped');
+    }
+    /**
+     * Get the full gateway status report.
+     *
+     * Aggregates per-channel readiness from the ChannelManager's status,
+     * the active set, and any recorded errors.
+     */
+    status() {
+        const channels = this.manager.getAllChannels();
+        const channelStatuses = [];
+        let connectedCount = 0;
+        let errorCount = 0;
+        let disconnectedCount = 0;
+        for (const channel of channels) {
+            const s = channel.getStatus();
+            const errorMsg = this.channelErrors.get(channel.type) ?? s.error;
+            let readiness;
+            if (errorMsg) {
+                readiness = 'error';
+                errorCount++;
+            }
+            else if (s.connected) {
+                readiness = 'connected';
+                connectedCount++;
+            }
+            else {
+                readiness = 'disconnected';
+                disconnectedCount++;
+            }
+            channelStatuses.push({
+                channelId: channel.type,
+                readiness,
+                authenticated: s.authenticated,
+                lastActivity: s.lastActivity?.toISOString(),
+                error: errorMsg,
+                info: s.info,
+            });
+        }
+        return {
+            ok: errorCount === 0 && channels.length > 0,
+            generatedAt: new Date().toISOString(),
+            totalChannels: channels.length,
+            connectedCount,
+            errorCount,
+            disconnectedCount,
+            channels: channelStatuses,
+        };
+    }
+    /**
+     * Check whether a specific channel is currently active.
+     */
+    isActive(channelId) {
+        return this.activeChannels.has(channelId);
+    }
+    /**
+     * Get the set of currently active channel IDs.
+     */
+    getActiveChannels() {
+        return [...this.activeChannels];
+    }
+}
+// ============================================================================
+// Singleton
+// ============================================================================
+let lifecycleInstance = null;
+/**
+ * Get the singleton GatewayLifecycleManager instance.
+ */
+export function getGatewayLifecycle() {
+    if (!lifecycleInstance) {
+        lifecycleInstance = new GatewayLifecycleManager();
+    }
+    return lifecycleInstance;
+}
+/**
+ * Reset the singleton (for testing).
+ */
+export function resetGatewayLifecycle() {
+    lifecycleInstance = null;
+}
+//# sourceMappingURL=gateway-lifecycle.js.map

package/dist/channels/google-chat/index.d.ts

@@ -158,7 +158,11 @@ export declare class GoogleChatChannel extends BaseChannel {
     private apiRequest;
     /**
      * Connect to Google Chat by validating the service account and
-     * verifying API access
+     * verifying API access.
+     *
+     * REST/webhook adapter — outbound via the Google Chat REST API, inbound via
+     * webhook (or Pub/Sub) callbacks; no persistent connection is held open
+     * here, so reconnection (ReconnectionManager) is N/A.
      */
     connect(): Promise<void>;
     /**

package/dist/channels/google-chat/index.js

@@ -139,7 +139,11 @@ export class GoogleChatChannel extends BaseChannel {
     // ==========================================================================
     /**
      * Connect to Google Chat by validating the service account and
-     * verifying API access
+     * verifying API access.
+     *
+     * REST/webhook adapter — outbound via the Google Chat REST API, inbound via
+     * webhook (or Pub/Sub) callbacks; no persistent connection is held open
+     * here, so reconnection (ReconnectionManager) is N/A.
      */
     async connect() {
         try {

package/dist/channels/imessage/index.d.ts

@@ -51,6 +51,8 @@ export declare class IMessageAdapter extends EventEmitter {
     private pollingTimer;
     private lastMessageTimestamp;
     private retryCount;
+    private reconnecting;
+    private reconnectionManager;
     constructor(config: IMessageConfig);
     start(): Promise<void>;
     stop(): Promise<void>;
@@ -70,6 +72,18 @@ export declare class IMessageAdapter extends EventEmitter {
     private startPolling;
     private stopPolling;
     private pollMessages;
+    /**
+     * Recover a dropped BlueBubbles connection via the shared
+     * ReconnectionManager (exponential backoff + jitter + max-retry
+     * exhaustion). Replaces the previous hand-rolled backoff loop so we
+     * never run two competing backoffs at once.
+     *
+     * `scheduleReconnect` is single-shot — one call schedules exactly one
+     * attempt — so on a failed health check we must re-drive it (the way
+     * discord's repeated WS `close` events and telegram's repeating poll loop
+     * naturally do) until the connection recovers or the manager exhausts its
+     * retries and emits `exhausted`.
+     */
     private reconnect;
     private getBaseUrl;
     private apiRequest;

package/dist/channels/imessage/index.js

@@ -8,6 +8,7 @@
 import { EventEmitter } from 'events';
 import { logger } from '../../utils/logger.js';
 import { BaseChannel } from '../core.js';
+import { ReconnectionManager } from '../reconnection-manager.js';
 // ============================================================================
 // IMessageAdapter
 // ============================================================================
@@ -17,6 +18,8 @@ export class IMessageAdapter extends EventEmitter {
     pollingTimer = null;
     lastMessageTimestamp = 0;
     retryCount = 0;
+    reconnecting = false;
+    reconnectionManager;
     constructor(config) {
         super();
         this.config = {
@@ -28,6 +31,13 @@ export class IMessageAdapter extends EventEmitter {
         if (this.config.port === undefined) {
             this.config.port = 1234;
         }
+        // Persistent long-poll connection to BlueBubbles — drops are recovered
+        // with shared exponential backoff (same idiom as discord/slack/telegram).
+        this.reconnectionManager = new ReconnectionManager('imessage', {
+            maxRetries: this.config.maxRetries ?? 5,
+            initialDelayMs: this.config.retryDelay ?? 5000,
+            maxDelayMs: 60000,
+        });
     }
     // ============================================================================
     // Lifecycle
@@ -42,6 +52,11 @@ export class IMessageAdapter extends EventEmitter {
         });
         // Verify connectivity
         await this.healthCheck();
+        // Connectivity is confirmed for this session — reset the shared backoff
+        // state so a fresh start() never inherits a pre-exhausted retryCount from
+        // a previous outage episode (onConnected() resets retryCount + active +
+        // any pending timer; cancel() alone does not).
+        this.reconnectionManager.onConnected();
         this.running = true;
         this.lastMessageTimestamp = Date.now();
         this.retryCount = 0;
@@ -54,6 +69,9 @@ export class IMessageAdapter extends EventEmitter {
         if (!this.running) {
             throw new Error('IMessageAdapter is not running');
         }
+        // Cancel any pending reconnect so it can't fire after an explicit stop.
+        this.reconnectionManager.cancel();
+        this.reconnecting = false;
         this.stopPolling();
         this.running = false;
         this.emit('disconnected');
@@ -147,6 +165,9 @@ export class IMessageAdapter extends EventEmitter {
             try {
                 await this.pollMessages();
                 this.retryCount = 0;
+                // A successful poll means the connection is healthy again — reset
+                // the shared backoff state so a future drop starts from delay 0.
+                this.reconnectionManager.onConnected();
             }
             catch (error) {
                 this.retryCount++;
@@ -155,7 +176,7 @@ export class IMessageAdapter extends EventEmitter {
                 if (this.retryCount >= (this.config.maxRetries || 5)) {
                     logger.error('IMessageAdapter: max retries exceeded, attempting reconnect');
                     this.emit('error', new Error('Polling failed after max retries'));
-                    await this.reconnect();
+                    this.reconnect();
                 }
             }
         }, this.config.pollingInterval);
@@ -193,32 +214,58 @@ export class IMessageAdapter extends EventEmitter {
     // ============================================================================
     // Reconnection
     // ============================================================================
-    async reconnect() {
+    /**
+     * Recover a dropped BlueBubbles connection via the shared
+     * ReconnectionManager (exponential backoff + jitter + max-retry
+     * exhaustion). Replaces the previous hand-rolled backoff loop so we
+     * never run two competing backoffs at once.
+     *
+     * `scheduleReconnect` is single-shot — one call schedules exactly one
+     * attempt — so on a failed health check we must re-drive it (the way
+     * discord's repeated WS `close` events and telegram's repeating poll loop
+     * naturally do) until the connection recovers or the manager exhausts its
+     * retries and emits `exhausted`.
+     */
+    reconnect() {
+        // Pause polling while we attempt to re-establish the connection; the
+        // backoff timer in the manager now owns the retry cadence.
         this.stopPolling();
-        const maxRetries = this.config.maxRetries || 5;
-        const retryDelay = this.config.retryDelay || 5000;
-        for (let attempt = 1; attempt <= maxRetries; attempt++) {
+        // Surface permanent failure once the manager exhausts its retries.
+        if (this.reconnectionManager.listenerCount('exhausted') === 0) {
+            this.reconnectionManager.on('exhausted', () => {
+                this.reconnecting = false;
+                this.running = false;
+                this.emit('disconnected', new Error('Reconnection failed after all retries'));
+                logger.error('IMessageAdapter: reconnection failed permanently');
+            });
+        }
+        this.reconnecting = true;
+        this.reconnectionManager.scheduleReconnect(async () => {
             try {
-                logger.info(`IMessageAdapter: reconnection attempt ${attempt}/${maxRetries}`);
                 await this.healthCheck();
-                // Reconnected successfully
+                // Health check passed — resume the poll loop and reset counters.
+                this.reconnecting = false;
                 this.retryCount = 0;
                 this.startPolling();
+                this.reconnectionManager.onConnected();
                 this.emit('reconnected');
                 logger.info('IMessageAdapter: reconnected successfully');
-                return;
             }
-            catch {
-                if (attempt < maxRetries) {
-                    const delay = retryDelay * Math.pow(2, attempt - 1);
-                    logger.warn(`IMessageAdapter: reconnection failed, retrying in ${delay}ms`);
-                    await new Promise(resolve => setTimeout(resolve, delay));
+            catch (error) {
+                // This attempt failed. Defer re-driving the manager until after it
+                // clears its internal `active` flag (which it does in its own
+                // `finally`, once this closure settles), so the next attempt is
+                // actually scheduled instead of being dropped by the active-guard.
+                if (this.running) {
+                    setTimeout(() => {
+                        if (this.running && this.reconnecting) {
+                            this.reconnect();
+                        }
+                    }, 0).unref?.();
                 }
+                throw error instanceof Error ? error : new Error(String(error));
             }
-        }
-        this.running = false;
-        this.emit('disconnected', new Error('Reconnection failed after all retries'));
-        logger.error('IMessageAdapter: reconnection failed permanently');
+        });
     }
     // ============================================================================
     // Internal Helpers

package/dist/channels/index.d.ts

@@ -48,3 +48,7 @@ export type { SynologyChatConfig, SynologyChatChannelConfig, SynologyChatMessage
 export { NtfyAdapter, NtfyChannel } from './ntfy/index.js';
 export type { NtfyConfig, NtfyChannelConfig, NtfyPublishOptions, NtfyPublishResult } from './ntfy/index.js';
 export { TwitchAdapter, TlonAdapter, GmailWebhookAdapter, DocsSearchTool } from './niche-channels.js';
+export { GatewayLifecycleManager, getGatewayLifecycle, resetGatewayLifecycle, } from './gateway-lifecycle.js';
+export type { ChannelReadiness, GatewayChannelStatus, GatewayStatus, } from './gateway-lifecycle.js';
+export { buildSlashParityManifest, buildPlatformParityReport, extractActualCommands, renderSlashParityManifest, EXPECTED_SLASH_COMMANDS, } from './slash-parity.js';
+export type { SlashCommandSpec, SlashCommandParityEntry, PlatformSlashParityReport, SlashParityManifest, SlashCommandProvider, } from './slash-parity.js';

package/dist/channels/index.js

@@ -49,4 +49,8 @@ export { SynologyChatAdapter, SynologyChatChannel } from './synology-chat/index.
 export { NtfyAdapter, NtfyChannel } from './ntfy/index.js';
 // Niche Channels (Twitch, Tlon, Gmail)
 export { TwitchAdapter, TlonAdapter, GmailWebhookAdapter, DocsSearchTool } from './niche-channels.js';
+// Gateway Lifecycle
+export { GatewayLifecycleManager, getGatewayLifecycle, resetGatewayLifecycle, } from './gateway-lifecycle.js';
+// Slash-Command Parity
+export { buildSlashParityManifest, buildPlatformParityReport, extractActualCommands, renderSlashParityManifest, EXPECTED_SLASH_COMMANDS, } from './slash-parity.js';
 //# sourceMappingURL=index.js.map

package/dist/channels/irc/index.d.ts

@@ -1,9 +1,13 @@
 /**
  * IRC Channel Adapter
  *
- * Connects to IRC servers for sending/receiving messages.
- * Supports multiple channels, SASL auth, and TLS.
+ * Connects to IRC servers for sending/receiving messages over a real,
+ * long-lived TCP (or TLS) socket implementing an RFC 1459/2812 subset.
+ * Supports multiple channels, password auth, TLS, and auto-reconnect with
+ * exponential backoff (shared ReconnectionManager idiom — same as
+ * imessage/discord/slack).
  */
+import { EventEmitter } from 'events';
 import { BaseChannel, ChannelConfig, DeliveryResult, OutboundMessage } from '../core.js';
 export interface IRCConfig {
     server: string;
@@ -15,6 +19,10 @@ export interface IRCConfig {
     channels: string[];
     useTLS?: boolean;
     sasl?: boolean;
+    /** Milliseconds to wait for the 001 welcome reply before failing connect (default 15000) */
+    connectTimeoutMs?: number;
+    maxRetries?: number;
+    retryDelayMs?: number;
 }
 export interface IRCChannelConfig extends ChannelConfig {
     server: string;
@@ -26,15 +34,76 @@ export interface IRCChannelConfig extends ChannelConfig {
     channels: string[];
     useTLS?: boolean;
     sasl?: boolean;
+    connectTimeoutMs?: number;
+    maxRetries?: number;
+    retryDelayMs?: number;
 }
-export declare class IRCAdapter {
+/**
+ * A single parsed IRC protocol line.
+ *
+ * IRC lines are either prefixed (`:<prefix> <command> <params...>`) or
+ * unprefixed (`<command> <params...>`). The final parameter may be a
+ * "trailing" param introduced by ` :` which can contain spaces.
+ */
+interface IRCMessage {
+    prefix?: string;
+    command: string;
+    params: string[];
+}
+/**
+ * Parse a raw IRC line (without the trailing CRLF) into prefix/command/params.
+ *
+ * Handles both prefixed and unprefixed lines — this distinction is
+ * load-bearing: the welcome reply `001 <nick> :Welcome` has NO prefix while
+ * `:nick!u@h PRIVMSG #cb :text` does. Treating tokens[0] as always-prefix (or
+ * never-prefix) misparses one of them.
+ */
+export declare function parseIRCLine(line: string): IRCMessage | null;
+export declare class IRCAdapter extends EventEmitter {
     private config;
     private running;
     private joinedChannels;
+    private socket;
+    private recvBuffer;
+    /** True while an intentional disconnect is in progress — suppresses reconnect. */
+    private closing;
+    /** True once a close/error for the current socket has been handled (de-dup). */
+    private closeHandled;
+    private reconnecting;
+    private reconnectionManager;
     constructor(config: IRCConfig);
     start(): Promise<void>;
     stop(): Promise<void>;
     isRunning(): boolean;
+    getConfig(): IRCConfig;
+    /**
+     * Open the socket, perform the registration handshake, and resolve once the
+     * server sends the 001 welcome numeric. Used by both start() and the
+     * reconnect callback (so it deliberately omits the running-guard).
+     */
+    private connectInternal;
+    /**
+     * Buffer incoming bytes and dispatch complete CRLF-terminated lines.
+     * `onWelcome` is invoked when the 001 numeric is seen (resolves connect()).
+     */
+    private handleData;
+    private handleLine;
+    private handlePrivmsg;
+    /**
+     * Handle a socket 'close' or 'error' that was NOT triggered by an
+     * intentional disconnect. De-dupes the error→close pair (ECONNRESET fires
+     * 'error' then 'close') and drives a single reconnect via the shared
+     * ReconnectionManager.
+     */
+    private handleSocketClosed;
+    /**
+     * Recover a dropped connection via the shared ReconnectionManager
+     * (exponential backoff + jitter + exhaustion). `scheduleReconnect` is
+     * single-shot, so a failed attempt re-drives it (deferred past the manager's
+     * internal active-guard) until recovery or exhaustion.
+     */
+    private reconnect;
+    private write;
     sendMessage(target: string, text: string): Promise<{
         success: boolean;
     }>;
@@ -57,3 +126,4 @@ export declare class IRCChannel extends BaseChannel {
     disconnect(): Promise<void>;
     send(message: OutboundMessage): Promise<DeliveryResult>;
 }
+export default IRCAdapter;