@phuetz/code-buddy 1.0.0 → 1.2.0

package/dist/channels/nostr/index.js

@@ -5,8 +5,12 @@
  * Supports NIP-04 encrypted direct messages.
  */
 import { createECDH, createHash, randomBytes } from 'crypto';
+import { sha256 } from '@noble/hashes/sha256';
+import { bytesToHex } from '@noble/hashes/utils';
+import { schnorr } from '@noble/curves/secp256k1';
 import { logger } from '../../utils/logger.js';
-import { BaseChannel } from '../core.js';
+import { BaseChannel, } from '../core.js';
+import { ReconnectionManager } from '../reconnection-manager.js';
 export class NostrAdapter {
     static BECH32_CHARSET = 'qpzry9x8gf2tvdw0s3jn54khce6mua7l';
     static BECH32_GENERATOR = [
@@ -78,6 +82,15 @@ export class NostrAdapter {
     getConfig() {
         return { ...this.config, relays: [...this.config.relays] };
     }
+    /**
+     * Resolve the configured secret as raw 32 bytes: 64-char hex as-is, `nsec...`
+     * bech32 decoded to its 32-byte payload, otherwise a deterministic sha256 of
+     * the arbitrary secret. No configured key => a fresh random 32 bytes.
+     * Public so {@link NostrChannel} signs under the *same* identity (esp. nsec).
+     */
+    getSecretKeyBytes() {
+        return this.resolvePrivateKeyBytes();
+    }
     resolvePrivateKeyBytes() {
         const raw = this.config.privateKey;
         if (!raw) {
@@ -201,9 +214,40 @@ export class NostrAdapter {
         return chk;
     }
 }
+/**
+ * Real Nostr relay channel (NIP-01).
+ *
+ * Opens persistent WebSocket connections to each configured relay, subscribes
+ * to kind-1 (text note) events via a `REQ` frame, and surfaces inbound events
+ * as `'message'` events on the channel. Dropped sockets are recovered with the
+ * shared {@link ReconnectionManager} (exponential backoff + jitter), the same
+ * idiom used by the discord/slack/imessage adapters.
+ *
+ * Connection semantics are *optimistic*: `connect()` marks the channel
+ * connected and returns immediately, opening sockets in the background. This
+ * mirrors how a real Nostr client behaves (any one of N relays may be down)
+ * and lets the channel come up even when a relay is unreachable.
+ *
+ * `NostrAdapter` (above) is retained unchanged as the key / bech32 / relay-list
+ * utility — its `start()`/`sendDirectMessage()` are legacy in-process stubs
+ * kept only for the existing unit tests. The real transport lives here.
+ */
 export class NostrChannel extends BaseChannel {
     adapter;
-    constructor(config) {
+    relays = [];
+    subId;
+    filters;
+    maxRetries;
+    reconnectDelayMs;
+    /** Set while an intentional disconnect is in progress so `close` skips reconnect. */
+    shuttingDown = false;
+    /** Injectable socket factory (defaults to the Node global `WebSocket`). */
+    socketFactory;
+    /** Outstanding publishes keyed by event id, resolved on the relay's `OK` ack. */
+    pendingPublishes = new Map();
+    /** How long to wait for a relay `["OK", id, ...]` ack before timing out. */
+    publishTimeoutMs;
+    constructor(config, socketFactory) {
         super('nostr', {
             type: 'nostr',
             enabled: config.enabled,
@@ -215,33 +259,120 @@ export class NostrChannel extends BaseChannel {
             rateLimit: config.rateLimit,
             options: config.options,
         });
+        const relayUrls = [
+            ...(Array.isArray(config.relays) ? config.relays : []),
+            ...(config.relay ? [config.relay] : []),
+        ].filter((u) => typeof u === 'string' && u.length > 0);
         this.adapter = new NostrAdapter({
             privateKey: config.privateKey,
-            relays: config.relays,
+            relays: relayUrls,
         });
+        this.filters = config.filters ?? {};
+        this.maxRetries = config.maxRetries ?? 10;
+        this.reconnectDelayMs = config.reconnectDelayMs ?? 1000;
+        this.publishTimeoutMs = config.publishTimeoutMs ?? 8000;
+        this.subId = `cb-${randomBytes(6).toString('hex')}`;
+        this.socketFactory =
+            socketFactory ??
+                ((url) => new globalThis.WebSocket(url));
+        this.relays = relayUrls.map((url) => ({
+            url,
+            socket: null,
+            reconnection: new ReconnectionManager(`nostr:${url}`, {
+                maxRetries: this.maxRetries,
+                initialDelayMs: this.reconnectDelayMs,
+                maxDelayMs: 60000,
+            }),
+        }));
     }
+    /**
+     * Optimistically connect: mark the channel up, emit `'connected'`, then open
+     * every relay socket in the background. Resolves immediately — it never waits
+     * on a socket `'open'`, so an unreachable relay can't block startup.
+     */
     async connect() {
-        await this.adapter.start();
+        this.shuttingDown = false;
         this.status.connected = true;
         this.status.authenticated = true;
         this.status.lastActivity = new Date();
         this.emit('connected', this.type);
+        for (const relay of this.relays) {
+            this.openRelay(relay);
+        }
     }
     async disconnect() {
         if (!this.status.connected)
             return;
-        await this.adapter.stop();
+        this.shuttingDown = true;
+        for (const relay of this.relays) {
+            relay.reconnection.cancel();
+            this.closeSocket(relay);
+        }
+        // Fail any in-flight publishes so awaiting `send()` calls can't hang.
+        for (const pending of this.pendingPublishes.values()) {
+            pending.resolve({ accepted: false, message: 'channel disconnected', relayUrl: '' });
+        }
+        this.pendingPublishes.clear();
         this.status.connected = false;
+        this.status.authenticated = false;
         this.status.lastActivity = new Date();
         this.emit('disconnected', this.type);
     }
+    /**
+     * Build, BIP-340 sign, and publish a Nostr kind-1 event for the outbound
+     * message.
+     *
+     * When a secret key is configured we derive the x-only `pubkey` and the
+     * Schnorr `sig` via `@noble/curves` (audited secp256k1/BIP-340), compute the
+     * canonical sha256 `id`, publish `["EVENT", event]` to every connected relay,
+     * and resolve from the relay's `["OK", id, accepted, msg]` acknowledgement.
+     *
+     * HONEST GATE: if NO secret key is configured we do NOT sign with a throwaway
+     * key — we return the same clear error as before. Live publishing is gated
+     * only on the operator providing their nsec/hex key + a reachable relay.
+     */
     async send(message) {
         try {
-            const result = await this.adapter.sendDirectMessage(message.channelId, message.content);
+            // Honesty guard: never sign with the random fallback key. A configured
+            // key is required to produce a publishable, attributable event.
+            if (!this.adapter.getConfig().privateKey) {
+                const unsigned = this.buildUnsignedEvent(message.content);
+                return {
+                    success: false,
+                    messageId: unsigned.id,
+                    error: 'Nostr send requires a configured secret key / signer (no key configured)',
+                    timestamp: new Date(),
+                };
+            }
+            const event = this.buildSignedEvent(message.content);
             this.status.lastActivity = new Date();
+            const sockets = this.relays
+                .map((r) => r.socket)
+                .filter((s) => s !== null && s.readyState === 1 /* OPEN */);
+            if (sockets.length === 0) {
+                return {
+                    success: false,
+                    messageId: event.id,
+                    error: 'Nostr send failed: no relay socket is open',
+                    timestamp: new Date(),
+                };
+            }
+            const ack = await this.publishToRelays(event, sockets);
+            if (ack.accepted) {
+                logger.debug('NostrChannel: relay accepted published event', {
+                    id: event.id,
+                    relay: ack.relayUrl,
+                });
+                return {
+                    success: true,
+                    messageId: event.id,
+                    timestamp: new Date(),
+                };
+            }
             return {
-                success: result.success,
-                messageId: result.eventId,
+                success: false,
+                messageId: event.id,
+                error: ack.message || 'Nostr relay rejected the event',
                 timestamp: new Date(),
             };
         }
@@ -253,6 +384,263 @@ export class NostrChannel extends BaseChannel {
             };
         }
     }
+    /**
+     * Publish a signed event to every open relay socket and resolve from the
+     * FIRST `["OK", id, ...]` acknowledgement (or a timeout). The pending entry is
+     * keyed by event id and resolved by {@link handleRelayData}'s `OK` branch.
+     */
+    publishToRelays(event, sockets) {
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.pendingPublishes.delete(event.id);
+                resolve({ accepted: false, message: 'timed out waiting for relay OK', relayUrl: '' });
+            }, this.publishTimeoutMs);
+            // Don't keep the event loop alive solely for this ack timer.
+            if (typeof timer.unref === 'function') {
+                timer.unref();
+            }
+            this.pendingPublishes.set(event.id, {
+                resolve: (ok) => {
+                    clearTimeout(timer);
+                    this.pendingPublishes.delete(event.id);
+                    resolve(ok);
+                },
+                timer,
+            });
+            const frame = JSON.stringify(['EVENT', event]);
+            for (const socket of sockets) {
+                try {
+                    socket.send(frame);
+                }
+                catch (error) {
+                    logger.debug('NostrChannel: failed to send EVENT frame', {
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            }
+        });
+    }
+    // ============================================================================
+    // Relay socket lifecycle
+    // ============================================================================
+    openRelay(relay) {
+        let socket;
+        try {
+            socket = this.socketFactory(relay.url);
+        }
+        catch (error) {
+            logger.warn('NostrChannel: failed to construct relay socket', {
+                url: relay.url,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            this.scheduleRelayReconnect(relay);
+            return;
+        }
+        relay.socket = socket;
+        socket.addEventListener('open', () => {
+            logger.debug('NostrChannel: relay open', { url: relay.url });
+            relay.reconnection.onConnected();
+            this.status.connected = true;
+            this.status.lastActivity = new Date();
+            this.sendSubscription(socket);
+        });
+        socket.addEventListener('message', (event) => {
+            const data = event.data;
+            this.handleRelayData(relay, data);
+        });
+        socket.addEventListener('error', (event) => {
+            const err = this.errorFromEvent(event);
+            logger.debug('NostrChannel: relay socket error', { url: relay.url, error: err.message });
+            // BaseChannel is an EventEmitter — only emit 'error' when someone listens,
+            // otherwise EventEmitter throws and crashes the process.
+            if (this.listenerCount('error') > 0) {
+                this.emit('error', this.type, err);
+            }
+        });
+        socket.addEventListener('close', () => {
+            relay.socket = null;
+            if (this.shuttingDown)
+                return;
+            logger.debug('NostrChannel: relay closed, scheduling reconnect', { url: relay.url });
+            this.scheduleRelayReconnect(relay);
+        });
+    }
+    scheduleRelayReconnect(relay) {
+        if (this.shuttingDown)
+            return;
+        relay.reconnection.scheduleReconnect(async () => {
+            if (this.shuttingDown)
+                return;
+            this.openRelay(relay);
+        });
+    }
+    sendSubscription(socket) {
+        const filter = { kinds: [1], ...this.filters };
+        const req = JSON.stringify(['REQ', this.subId, filter]);
+        try {
+            socket.send(req);
+        }
+        catch (error) {
+            logger.debug('NostrChannel: failed to send REQ', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    handleRelayData(relay, data) {
+        let frame;
+        try {
+            const text = typeof data === 'string' ? data : String(data);
+            frame = JSON.parse(text);
+        }
+        catch {
+            logger.debug('NostrChannel: ignoring non-JSON relay frame', { url: relay.url });
+            return;
+        }
+        if (!Array.isArray(frame) || frame.length === 0)
+            return;
+        const kind = frame[0];
+        if (kind === 'EVENT') {
+            // ["EVENT", <subId>, <event>]
+            const event = frame[2];
+            if (event && typeof event === 'object') {
+                this.emitInbound(event, relay.url);
+            }
+            return;
+        }
+        if (kind === 'EOSE') {
+            // End of stored events — nothing to do.
+            return;
+        }
+        if (kind === 'NOTICE') {
+            logger.info('NostrChannel: relay NOTICE', { url: relay.url, message: String(frame[1] ?? '') });
+            return;
+        }
+        if (kind === 'OK') {
+            // Publish acknowledgement: ["OK", <eventId>, <ok>, <message>]
+            const eventId = typeof frame[1] === 'string' ? frame[1] : '';
+            const accepted = frame[2] === true;
+            const message = typeof frame[3] === 'string' ? frame[3] : '';
+            logger.debug('NostrChannel: relay OK', { url: relay.url, eventId, accepted, message });
+            const pending = this.pendingPublishes.get(eventId);
+            if (pending) {
+                pending.resolve({ accepted, message, relayUrl: relay.url });
+            }
+            return;
+        }
+    }
+    emitInbound(event, relayUrl) {
+        const content = typeof event.content === 'string' ? event.content : '';
+        const pubkey = typeof event.pubkey === 'string' ? event.pubkey : 'unknown';
+        const id = typeof event.id === 'string' ? event.id : `nostr-${Date.now()}`;
+        const createdAt = typeof event.created_at === 'number' ? event.created_at : Math.floor(Date.now() / 1000);
+        const inbound = {
+            id,
+            channel: {
+                id: relayUrl,
+                type: 'nostr',
+                name: relayUrl,
+                isDM: false,
+            },
+            sender: {
+                id: pubkey,
+                username: pubkey,
+            },
+            content,
+            contentType: 'text',
+            timestamp: new Date(createdAt * 1000),
+            raw: event,
+        };
+        this.status.lastActivity = new Date();
+        const parsed = this.parseCommand(inbound);
+        this.emit('message', parsed);
+        if (parsed.isCommand) {
+            this.emit('command', parsed);
+        }
+    }
+    /**
+     * Build the canonical unsigned Nostr event for `content`. The `id` is the
+     * sha256 of the NIP-01 serialization `[0, pubkey, created_at, kind, tags,
+     * content]`. Used for the honest no-key error path (still surfaces a real id).
+     */
+    buildUnsignedEvent(content) {
+        const pubkey = this.getPublicKeyHex();
+        const created_at = Math.floor(Date.now() / 1000);
+        const kind = 1;
+        const tags = [];
+        const serialized = JSON.stringify([0, pubkey, created_at, kind, tags, content]);
+        const id = bytesToHex(sha256(new TextEncoder().encode(serialized)));
+        return { id, pubkey, created_at, kind, tags, content };
+    }
+    /**
+     * Build a fully BIP-340 signed Nostr kind-1 event for `content`.
+     *
+     * `pubkey` and `sig` are derived from the same secp256k1 secret via
+     * `@noble/curves`' Schnorr primitives: `schnorr.getPublicKey` yields the
+     * x-only pubkey (correct BIP-340 even-y normalization), `id` is the sha256 of
+     * the NIP-01 serialization, and `sig = schnorr.sign(id, sk)`. Nostr signs the
+     * 32-byte id directly (no extra pre-hash), which is exactly noble's raw-message
+     * contract — so `schnorr.verify(sig, id, pubkey)` round-trips.
+     */
+    buildSignedEvent(content) {
+        const sk = this.resolvePrivateKeyBytes();
+        const pubkey = bytesToHex(schnorr.getPublicKey(sk));
+        const created_at = Math.floor(Date.now() / 1000);
+        const kind = 1;
+        const tags = [];
+        const serialized = JSON.stringify([0, pubkey, created_at, kind, tags, content]);
+        const id = bytesToHex(sha256(new TextEncoder().encode(serialized)));
+        const sig = bytesToHex(schnorr.sign(id, sk));
+        return { id, pubkey, created_at, kind, tags, content, sig };
+    }
+    /** x-only 32-byte public key as lowercase hex (Nostr event `pubkey` field). */
+    getPublicKeyHex() {
+        return bytesToHex(schnorr.getPublicKey(this.resolvePrivateKeyBytes()));
+    }
+    /**
+     * Resolve the signing secret as raw 32 bytes. Delegates to the adapter's
+     * canonical resolver so hex AND `nsec...` bech32 keys decode to the SAME
+     * identity the operator configured (a duplicated resolver here previously
+     * dropped the nsec branch and silently signed under a sha256-derived key).
+     */
+    resolvePrivateKeyBytes() {
+        return this.adapter.getSecretKeyBytes();
+    }
+    closeSocket(relay) {
+        const socket = relay.socket;
+        relay.socket = null;
+        if (!socket)
+            return;
+        try {
+            // Prefer terminate(): the socket may still be CONNECTING against a dead
+            // relay, where close() would hang waiting for a handshake that won't come.
+            if (typeof socket.terminate === 'function') {
+                socket.terminate();
+            }
+            else {
+                socket.close();
+            }
+        }
+        catch (error) {
+            logger.debug('NostrChannel: error closing relay socket', {
+                url: relay.url,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    errorFromEvent(event) {
+        if (event instanceof Error)
+            return event;
+        const maybe = event;
+        if (maybe?.error instanceof Error)
+            return maybe.error;
+        if (typeof maybe?.message === 'string')
+            return new Error(maybe.message);
+        return new Error('Nostr relay socket error');
+    }
+    /** Expose the configured relay URLs (post construction). */
+    getRelayUrls() {
+        return this.relays.map((r) => r.url);
+    }
 }
 export default NostrAdapter;
 //# sourceMappingURL=index.js.map

package/dist/channels/ntfy/index.js

@@ -99,6 +99,9 @@ export class NtfyChannel extends BaseChannel {
             tags: config.tags,
         });
     }
+    // REST adapter — outbound messages are one-shot HTTP POSTs to an ntfy topic;
+    // there is no persistent subscription stream held open here, so reconnection
+    // (ReconnectionManager) is N/A.
     async connect() {
         await this.adapter.start();
         this.status.connected = true;

package/dist/channels/qq/index.js

@@ -97,6 +97,9 @@ export class QQChannel extends BaseChannel {
             autoEscape: config.autoEscape,
         });
     }
+    // REST adapter — outbound messages are one-shot HTTP POSTs to a OneBot v11
+    // gateway; there is no persistent connection held open here, so reconnection
+    // (ReconnectionManager) is N/A.
     async connect() {
         await this.adapter.start();
         this.status.connected = true;

package/dist/channels/slash-parity.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Per-Platform Slash-Command Parity Manifest
+ *
+ * Defines the expected slash commands per messaging platform and
+ * compares them against the actual registered commands per adapter.
+ * Returns a machine-readable readiness report for each platform.
+ */
+import type { ChannelType, BaseChannel } from './core.js';
+import { ChannelManager } from './core.js';
+/**
+ * Describes a single expected slash command on a platform.
+ */
+export interface SlashCommandSpec {
+    /** Command name (without leading /) */
+    name: string;
+    /** Human-readable description */
+    description: string;
+    /** Whether this command is required for parity (default: true) */
+    required?: boolean;
+}
+/**
+ * Per-platform parity result for a single command.
+ */
+export interface SlashCommandParityEntry {
+    /** Command name */
+    name: string;
+    /** Whether this command is present on the platform adapter */
+    present: boolean;
+    /** Whether this command is required */
+    required: boolean;
+}
+/**
+ * Per-platform parity report.
+ */
+export interface PlatformSlashParityReport {
+    /** Platform identifier */
+    platform: ChannelType;
+    /** Whether the platform adapter is registered in the channel manager */
+    adapterRegistered: boolean;
+    /** Total expected commands */
+    expectedCount: number;
+    /** Number of commands present on the adapter */
+    presentCount: number;
+    /** Number of missing required commands */
+    missingRequiredCount: number;
+    /** Number of missing optional commands */
+    missingOptionalCount: number;
+    /** Per-command parity entries */
+    commands: SlashCommandParityEntry[];
+    /** Overall parity status */
+    status: 'full' | 'partial' | 'none' | 'no-adapter';
+}
+/**
+ * Full parity manifest across all platforms.
+ */
+export interface SlashParityManifest {
+    /** Generation timestamp */
+    generatedAt: string;
+    /** Overall parity status */
+    ok: boolean;
+    /** Total platforms checked */
+    totalPlatforms: number;
+    /** Number of platforms with full parity */
+    fullParityCount: number;
+    /** Number of platforms with partial parity */
+    partialParityCount: number;
+    /** Number of platforms with no parity (missing adapter) */
+    noAdapterCount: number;
+    /** Per-platform reports */
+    platforms: PlatformSlashParityReport[];
+}
+/**
+ * The canonical set of slash commands expected on each platform.
+ *
+ * These represent the Code Buddy bot commands that users should be
+ * able to invoke from each messaging platform. The manifest is
+ * intentionally conservative — platforms may support additional
+ * commands beyond what is listed here.
+ */
+export declare const EXPECTED_SLASH_COMMANDS: Record<string, SlashCommandSpec[]>;
+/**
+ * Interface for adapters that expose their registered commands.
+ *
+ * Channel adapters can optionally implement this interface to
+ * allow the parity checker to extract their actual registered
+ * commands. Otherwise, fallback heuristics are used.
+ */
+export interface SlashCommandProvider {
+    /** Return the list of registered slash command names (without leading /) */
+    getRegisteredCommands(): string[];
+}
+/**
+ * Extract the actual registered commands from a channel adapter.
+ *
+ * Uses the SlashCommandProvider interface if available, otherwise
+ * returns an empty array (no commands can be detected).
+ */
+export declare function extractActualCommands(channel: BaseChannel): string[];
+/**
+ * Build a parity report for a single platform.
+ *
+ * @param platform - The platform channel type
+ * @param expectedCommands - The expected slash commands
+ * @param actualCommands - The actual registered commands
+ * @param adapterRegistered - Whether the adapter is in the ChannelManager
+ */
+export declare function buildPlatformParityReport(platform: ChannelType, expectedCommands: SlashCommandSpec[], actualCommands: string[], adapterRegistered: boolean): PlatformSlashParityReport;
+/**
+ * Build the full slash-command parity manifest across all tracked platforms.
+ *
+ * @param manager - Optional ChannelManager instance (defaults to singleton)
+ */
+export declare function buildSlashParityManifest(manager?: ChannelManager): SlashParityManifest;
+/**
+ * Render the parity manifest as a human-readable text report.
+ */
+export declare function renderSlashParityManifest(manifest: SlashParityManifest): string;