@pellux/goodvibes-tui 1.27.1 → 2.0.2

package/src/daemon/handlers/inbox/provider-adapter.ts

@@ -1,156 +0,0 @@
-// ---------------------------------------------------------------------------
-// Inbound provider adapter contract + registry.
-//
-// Each adapter owns ONE provider (slack, discord, email, ...). The poller calls
-// adapter.poll() on a cadence, dedups by item.id, and persists into the cursor
-// store. Adapters resolve credentials ONLY through the daemon credential store
-// and NEVER return raw sender ids or unredacted bodies — mapping/redaction is
-// the adapter's responsibility (see mapping helpers in `./mapping.ts`).
-//
-// CRITICAL: when a credential is missing/misconfigured an adapter returns
-// state 'unavailable' WITH an error string. It is NEVER silently omitted — the
-// caller must be able to distinguish "configured-but-empty" from "not wired".
-// ---------------------------------------------------------------------------
-
-import type { DaemonCredentialStore } from '../credentials.ts';
-import type { HandlerLogger } from '../context.ts';
-
-/**
- * Daemon-internal inbound item. This is NOT the SDK wire shape — the inbox
- * surface maps it onto the SDK `CHANNEL_INBOX_ITEM_SCHEMA` shape
- * (`from`/`subject`/`bodyPreview`/...) before returning. `fromDigest` is the
- * redacted sender (the only sender value that ever leaves the daemon).
- */
-export interface InboundChannelItem {
-  /** Stable, provider-scoped dedup key. Idempotent across polls. */
-  id: string;
-  provider: string;
-  kind: 'dm' | 'thread' | 'mention' | 'reaction';
-  /**
-   * sha256First(senderExternalId, 16) — NEVER the raw id. 16 hex chars == the
-   * first 8 bytes of the SHA-256 digest.
-   */
-  fromDigest: string;
-  /** <= 200 chars, safe for display. */
-  subjectPreview: string;
-  /** <= 500 chars, plain text, PII-stripped. */
-  bodyPreview: string;
-  /** Daemon route binding id, when resolvable. */
-  routeId?: string;
-  /** Unix ms. */
-  receivedAt: number;
-  unread: boolean;
-  /** Optional triage metadata written by the triage surface (read-only here). */
-  triageScore?: number;
-  triageTags?: string[];
-}
-
-export type ProviderState = 'ready' | 'unavailable' | 'empty';
-
-export interface ProviderPollResult {
-  items: InboundChannelItem[];
-  state: ProviderState;
-  /** Present only when state === 'unavailable'. */
-  error?: string;
-}
-
-export interface ProviderPollOptions {
-  /** Only return items newer than this Unix-ms timestamp, when supported. */
-  since?: number;
-  /** Max items to return this poll. */
-  limit: number;
-}
-
-/** Context handed to every adapter at construction time. */
-export interface AdapterContext {
-  readonly credentials: DaemonCredentialStore;
-  readonly logger: HandlerLogger;
-  /**
-   * Optional route resolver supplied by the routing surface. Returns the route
-   * binding id for a given inbound item, or undefined when no route matches /
-   * the routing surface is not wired yet. Adapters/poller call this best-effort.
-   */
-  readonly resolveRouteId?: RouteResolver;
-}
-
-/**
- * Best-effort route resolution seam. The routing surface injects its
- * profile-backed implementation via the inbox bridge. Until then it is
- * undefined and items carry no routeId.
- */
-export type RouteResolver = (input: {
-  provider: string;
-  fromDigest: string;
-  kind: InboundChannelItem['kind'];
-}) => Promise<string | undefined> | string | undefined;
-
-export interface InboundProviderAdapter {
-  /** Provider id, e.g. 'slack'. Must be unique within the registry. */
-  readonly id: string;
-  /**
-   * Poll cadence in ms. Slack/Discord 30s, email 60s, everything else 120s.
-   * The poller reads this to schedule its per-provider interval.
-   */
-  readonly pollIntervalMs: number;
-  /**
-   * Pull recent DMs/threads/mentions. MUST resolve (never reject) — failures
-   * are reported via state:'unavailable' + error so one bad provider cannot
-   * crash the aggregate feed.
-   */
-  poll(opts: ProviderPollOptions): Promise<ProviderPollResult>;
-}
-
-/** Factory signature: adapters are constructed lazily with shared context. */
-export type AdapterFactory = (ctx: AdapterContext) => InboundProviderAdapter;
-
-// ---------------------------------------------------------------------------
-// Cadence constants (single source of truth, referenced by adapters + tests).
-// ---------------------------------------------------------------------------
-
-export const POLL_CADENCE_MS = {
-  realtime: 30_000, // slack, discord
-  email: 60_000,
-  default: 120_000,
-} as const;
-
-// ---------------------------------------------------------------------------
-// Registry
-// ---------------------------------------------------------------------------
-
-const FACTORIES = new Map<string, AdapterFactory>();
-
-/** Register a provider factory. Last registration for an id wins (idempotent). */
-export function registerAdapterFactory(id: string, factory: AdapterFactory): void {
-  FACTORIES.set(id, factory);
-}
-
-/** All registered provider ids, in insertion order. */
-export function registeredProviderIds(): string[] {
-  return [...FACTORIES.keys()];
-}
-
-/**
- * Construct adapters for the requested provider ids (or all registered ids when
- * `requested` is undefined/empty). Unknown ids are dropped: the returned map
- * only contains known providers.
- */
-export function buildAdapters(
-  ctx: AdapterContext,
-  requested?: readonly string[],
-): Map<string, InboundProviderAdapter> {
-  const ids = requested && requested.length > 0
-    ? requested.filter((id) => FACTORIES.has(id))
-    : registeredProviderIds();
-  const out = new Map<string, InboundProviderAdapter>();
-  for (const id of ids) {
-    const factory = FACTORIES.get(id);
-    if (!factory) continue;
-    out.set(id, factory(ctx));
-  }
-  return out;
-}
-
-/** Test/seam hook: clear the registry. */
-export function clearAdapterRegistry(): void {
-  FACTORIES.clear();
-}

package/src/daemon/handlers/inbox/providers/discord.ts

@@ -1,252 +0,0 @@
-// ---------------------------------------------------------------------------
-// Discord inbound adapter.
-//
-// Transport note (contract fidelity): the daemon-handoff checklist names the
-// Discord Gateway for DM polling. The Gateway is a persistent websocket push
-// transport and cannot be driven by the inbound poller, whose contract is a
-// stateless, cadence-driven adapter.poll() that MUST resolve each call (see
-// provider-adapter.ts) — a long-lived socket the poller neither owns nor
-// supervises is out of scope for that contract. We therefore satisfy the
-// DM-polling goal over Discord's supported request/response surface, the REST
-// API — the same DM data the Gateway streams, fetched on the poll cadence and
-// paged so a busy DM is never truncated:
-//   GET /users/@me/channels        -> list DM channels the bot participates in
-//   GET /channels/{id}/messages    -> recent messages per DM channel (paged via
-//                                   the `before` snowflake cursor)
-//
-// Discord snowflake ids encode their creation timestamp, so receivedAt is
-// derived from the message id (snowflake) when no explicit timestamp is present.
-//
-// Credential: surfaces.discord.botToken. Missing => 'unavailable'.
-// Cadence: 30s (realtime tier).
-// ---------------------------------------------------------------------------
-
-import type {
-  AdapterContext,
-  InboundChannelItem,
-  InboundProviderAdapter,
-  ProviderPollOptions,
-  ProviderPollResult,
-} from '../provider-adapter.ts';
-import { POLL_CADENCE_MS } from '../provider-adapter.ts';
-import { digestSender, toBodyPreview, toSubjectPreview } from '../mapping.ts';
-import { resolveRouteId } from './route-util.ts';
-import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
-
-const DISCORD_API = 'https://discord.com/api/v10';
-// Discord epoch (2015-01-01T00:00:00Z) in ms, used to decode snowflakes.
-const DISCORD_EPOCH_MS = 1_420_070_400_000;
-export const DISCORD_PROVIDER_ID = 'discord';
-export const DISCORD_CREDENTIAL_KEY = 'surfaces.discord.botToken';
-
-interface DiscordChannel {
-  id: string;
-  type: number; // 1 = DM, 3 = group DM
-}
-
-interface DiscordSelf {
-  id: string;
-}
-
-interface DiscordReaction {
-  count?: number;
-  emoji?: { id?: string | null; name?: string | null };
-}
-
-interface DiscordMessage {
-  id: string;
-  channel_id?: string;
-  content?: string;
-  timestamp?: string; // ISO-8601
-  author?: { id: string; bot?: boolean };
-  referenced_message?: unknown;
-  mentions?: Array<{ id: string }>;
-  reactions?: DiscordReaction[];
-}
-
-/**
- * Classify a Discord message into the InboundChannelItem `kind`.
- *   - reaction: someone reacted to OUR OWN message — a genuine inbound reaction
- *               event. Requires the message to be authored by us (its author id
- *               is selfId) AND to carry a non-empty reactions[]. A message
- *               authored by someone else that merely carries reactions[] is a
- *               normal DM, not a reaction event.
- *   - mention:  the message mentions us (our id is in mentions[])
- *   - thread:   the message is a reply (referenced_message present)
- *   - dm:       a plain direct message
- * Reaction outranks mention which outranks thread/dm (most-specific first).
- */
-function classifyDiscordKind(
-  msg: DiscordMessage,
-  selfId: string | undefined,
-): InboundChannelItem['kind'] {
-  if (
-    selfId &&
-    msg.author?.id === selfId &&
-    Array.isArray(msg.reactions) &&
-    msg.reactions.length > 0
-  ) {
-    return 'reaction';
-  }
-  if (selfId && Array.isArray(msg.mentions) && msg.mentions.some((m) => m.id === selfId)) {
-    return 'mention';
-  }
-  if (msg.referenced_message) return 'thread';
-  return 'dm';
-}
-
-/** Decode a Discord snowflake id to its creation Unix-ms timestamp. */
-function snowflakeToMs(id: string): number {
-  try {
-    const asBig = BigInt(id);
-    return Number((asBig >> 22n)) + DISCORD_EPOCH_MS;
-  } catch {
-    return 0;
-  }
-}
-
-async function discordGet<T>(token: string, path: string): Promise<T> {
-  const res = await fetch(`${DISCORD_API}${path}`, {
-    method: 'GET',
-    headers: {
-      Authorization: `Bot ${token}`,
-      Accept: 'application/json',
-    },
-  });
-  if (res.status === 401) throw new Error('Discord authentication failed (401)');
-  if (!res.ok) throw new Error(`Discord GET ${path} HTTP ${res.status}`);
-  return (await res.json()) as T;
-}
-
-export function createDiscordAdapter(ctx: AdapterContext): InboundProviderAdapter {
-  return {
-    id: DISCORD_PROVIDER_ID,
-    pollIntervalMs: POLL_CADENCE_MS.realtime,
-    async poll(opts: ProviderPollOptions): Promise<ProviderPollResult> {
-      let token: string | null;
-      try {
-        token = await ctx.credentials.resolveConfigSecret(DISCORD_CREDENTIAL_KEY);
-      } catch (error) {
-        return unavailable(`credential lookup failed: ${errMsg(error)}`);
-      }
-      if (!token || token.trim().length === 0) {
-        return unavailable('missing surfaces.discord.botToken');
-      }
-
-      // Resolve our own user id so we can classify @-mentions of us. Best-effort:
-      // a failure only disables mention classification, never the provider.
-      let selfId: string | undefined;
-      try {
-        const self = await discordGet<DiscordSelf>(token, '/users/@me');
-        if (self.id) selfId = self.id;
-      } catch (error) {
-        ctx.logger.warn('discord /users/@me failed; mentions will not be classified', {
-          error: errMsg(error),
-        });
-      }
-
-      try {
-        const channels = await discordGet<DiscordChannel[]>(token, '/users/@me/channels');
-        const dmChannels = channels.filter((c) => c.type === 1 || c.type === 3);
-        const items: InboundChannelItem[] = [];
-        // /channels/{id}/messages returns at most `perChannel` (<=50) messages
-        // newest-first. A DM that accrued more than one page of new messages in
-        // the `since` window would silently drop the oldest beyond the first page
-        // unless we page backwards via the `before` cursor (the id of the oldest
-        // message seen so far). MAX_HISTORY_PAGES bounds the walk.
-        const MAX_HISTORY_PAGES = 20;
-        const perChannel = Math.min(opts.limit, 50);
-        channelLoop: for (const channel of dmChannels) {
-          if (items.length >= opts.limit) break;
-          let before: string | undefined;
-          for (let page = 0; page < MAX_HISTORY_PAGES; page += 1) {
-            const params = new URLSearchParams({ limit: String(perChannel) });
-            // Discord treats after/before/around as mutually exclusive: sending
-            // both silently drops older in-window messages. Use `after` only on
-            // the first page (to bound the window at `since`); once paging
-            // backwards via `before`, drop `after` and rely on the
-            // oldestMs<=since stop condition below to terminate the walk.
-            if (before) params.set('before', before);
-            else if (opts.since) params.set('after', msToSnowflake(opts.since));
-            let messages: DiscordMessage[];
-            try {
-              messages = await discordGet<DiscordMessage[]>(
-                token,
-                `/channels/${channel.id}/messages?${params.toString()}`,
-              );
-            } catch (error) {
-              ctx.logger.warn('discord channel messages failed', {
-                channel: channel.id,
-                error: errMsg(error),
-              });
-              continue channelLoop;
-            }
-            if (messages.length === 0) break;
-            // Track the oldest id on this page for the next `before` cursor before
-            // we filter/skip, so pagination is driven by the raw page, not by what
-            // survived classification.
-            let oldestId: string | undefined;
-            let oldestMs = Number.POSITIVE_INFINITY;
-            for (const msg of messages) {
-              const msgMs = msg.timestamp
-                ? Date.parse(msg.timestamp) || snowflakeToMs(msg.id)
-                : snowflakeToMs(msg.id);
-              if (msgMs < oldestMs) {
-                oldestMs = msgMs;
-                oldestId = msg.id;
-              }
-              if (items.length >= opts.limit) break;
-              if (msg.author?.bot) continue;
-              const receivedAt = msgMs;
-              if (opts.since && receivedAt <= opts.since) continue;
-              const senderId = msg.author?.id ?? channel.id;
-              // Contract: fromDigest is SHA-256 (first 16 hex == 8 bytes) of the
-              // provider user id. Discord user ids (snowflakes) are globally
-              // unique, and the item.id / provider fields already namespace by
-              // provider.
-              const fromDigest = digestSender(senderId);
-              const kind = classifyDiscordKind(msg, selfId);
-              const item: InboundChannelItem = {
-                id: `discord:${channel.id}:${msg.id}`,
-                provider: DISCORD_PROVIDER_ID,
-                kind,
-                fromDigest,
-                subjectPreview: toSubjectPreview('Direct message'),
-                bodyPreview: toBodyPreview(msg.content),
-                receivedAt,
-                unread: true,
-              };
-              const routeId = await resolveRouteId(ctx, DISCORD_PROVIDER_ID, fromDigest, kind);
-              if (routeId) item.routeId = routeId;
-              items.push(item);
-            }
-            // Stop paging this channel when the page was not full (no older
-            // messages exist), the item budget is spent, or the oldest message on
-            // this page is already at/older than the `since` floor.
-            if (messages.length < perChannel || items.length >= opts.limit) break;
-            if (opts.since && oldestMs <= opts.since) break;
-            if (!oldestId) break;
-            before = oldestId;
-          }
-        }
-        return { items, state: items.length > 0 ? 'ready' : 'empty' };
-      } catch (error) {
-        return unavailable(errMsg(error));
-      }
-    },
-  };
-}
-
-/** Build a synthetic snowflake from a Unix-ms timestamp for the `after` cursor. */
-function msToSnowflake(ms: number): string {
-  const delta = Math.max(0, Math.floor(ms) - DISCORD_EPOCH_MS);
-  return (BigInt(delta) << 22n).toString();
-}
-
-function unavailable(error: string): ProviderPollResult {
-  return { items: [], state: 'unavailable', error };
-}
-
-function errMsg(error: unknown): string {
-  return summarizeError(error);
-}

package/src/daemon/handlers/inbox/providers/email.ts

@@ -1,152 +0,0 @@
-// ---------------------------------------------------------------------------
-// Email (IMAP) inbound adapter.
-//
-// Uses the dependency-free ImapClient (node:tls) to pull recent INBOX messages.
-// Connection params resolve through the daemon credential store (env/secrets
-// backend) so nothing sensitive is read from plaintext config:
-//   surfaces.email.imapHost      (e.g. imap.fastmail.com)
-//   surfaces.email.imapPort      (default 993)
-//   surfaces.email.imapUser
-//   surfaces.email.imapPassword  (app password / token)
-//
-// Any missing required field => state 'unavailable' WITH an explanatory error.
-// Cadence: 60s (email tier).
-// ---------------------------------------------------------------------------
-
-import type {
-  AdapterContext,
-  InboundChannelItem,
-  InboundProviderAdapter,
-  ProviderPollOptions,
-  ProviderPollResult,
-} from '../provider-adapter.ts';
-import { POLL_CADENCE_MS } from '../provider-adapter.ts';
-import { digestSender, toBodyPreview, toSubjectPreview } from '../mapping.ts';
-import { resolveRouteId } from './route-util.ts';
-import { ImapClient } from './imap-client.ts';
-import type { ImapConfig, ImapEnvelope } from './imap-client.ts';
-import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
-
-export const EMAIL_PROVIDER_ID = 'email';
-export const EMAIL_HOST_KEY = 'surfaces.email.imapHost';
-export const EMAIL_PORT_KEY = 'surfaces.email.imapPort';
-export const EMAIL_USER_KEY = 'surfaces.email.imapUser';
-export const EMAIL_PASSWORD_KEY = 'surfaces.email.imapPassword';
-
-/**
- * Injectable client factory so tests can substitute a fake IMAP client without
- * opening a TLS socket. Production default constructs the real ImapClient.
- */
-export interface ImapLike {
-  connect(): Promise<void>;
-  login(): Promise<void>;
-  select(mailbox?: string): Promise<void>;
-  searchUids(since?: number): Promise<number[]>;
-  fetchEnvelopes(uids: readonly number[]): Promise<ImapEnvelope[]>;
-  logout(): Promise<void>;
-  close(): void;
-}
-
-export type ImapClientFactory = (cfg: ImapConfig) => ImapLike;
-
-const defaultFactory: ImapClientFactory = (cfg) => new ImapClient(cfg);
-
-export function createEmailAdapter(
-  ctx: AdapterContext,
-  factory: ImapClientFactory = defaultFactory,
-): InboundProviderAdapter {
-  return {
-    id: EMAIL_PROVIDER_ID,
-    pollIntervalMs: POLL_CADENCE_MS.email,
-    async poll(opts: ProviderPollOptions): Promise<ProviderPollResult> {
-      let host: string | null;
-      let user: string | null;
-      let password: string | null;
-      let portRaw: string | null;
-      try {
-        [host, portRaw, user, password] = await Promise.all([
-          ctx.credentials.resolveConfigSecret(EMAIL_HOST_KEY),
-          ctx.credentials.resolveConfigSecret(EMAIL_PORT_KEY),
-          ctx.credentials.resolveConfigSecret(EMAIL_USER_KEY),
-          ctx.credentials.resolveConfigSecret(EMAIL_PASSWORD_KEY),
-        ]);
-      } catch (error) {
-        return unavailable(`credential lookup failed: ${errMsg(error)}`);
-      }
-
-      const missing: string[] = [];
-      if (!host) missing.push('imapHost');
-      if (!user) missing.push('imapUser');
-      if (!password) missing.push('imapPassword');
-      if (missing.length > 0) {
-        return unavailable(`missing email IMAP credentials: ${missing.join(', ')}`);
-      }
-      const port = portRaw ? Number.parseInt(portRaw, 10) : 993;
-      if (!Number.isFinite(port) || port <= 0) {
-        return unavailable(`invalid surfaces.email.imapPort: ${portRaw}`);
-      }
-
-      const client = factory({
-        host: host!,
-        port,
-        user: user!,
-        password: password!,
-      });
-
-      try {
-        await client.connect();
-        await client.login();
-        await client.select('INBOX');
-        const uids = await client.searchUids(opts.since);
-        // Newest UIDs first, capped at limit.
-        const selected = uids.sort((a, b) => b - a).slice(0, opts.limit);
-        const envelopes = await client.fetchEnvelopes(selected);
-        const items: InboundChannelItem[] = [];
-        for (const env of envelopes) {
-          const receivedAt = env.date > 0 ? env.date : Date.now();
-          if (opts.since && receivedAt <= opts.since) continue;
-          const fromDigest = digestSender(`email:${normalizeAddress(env.from)}`);
-          const kind = 'dm';
-          const item: InboundChannelItem = {
-            id: `email:${user}:${env.uid}`,
-            provider: EMAIL_PROVIDER_ID,
-            kind,
-            fromDigest,
-            subjectPreview: toSubjectPreview(env.subject),
-            bodyPreview: toBodyPreview(env.bodyPreview),
-            receivedAt,
-            unread: !env.seen,
-          };
-          const routeId = await resolveRouteId(ctx, EMAIL_PROVIDER_ID, fromDigest, kind);
-          if (routeId) item.routeId = routeId;
-          items.push(item);
-        }
-        return { items, state: items.length > 0 ? 'ready' : 'empty' };
-      } catch (error) {
-        return unavailable(errMsg(error));
-      } finally {
-        try {
-          await client.logout();
-        } catch {
-          // ignore
-        }
-        client.close();
-      }
-    },
-  };
-}
-
-/** Extract a bare address from a `Name <addr@host>` From header for digesting. */
-function normalizeAddress(from: string): string {
-  const angle = /<([^>]+)>/.exec(from);
-  const addr = (angle ? angle[1]! : from).trim().toLowerCase();
-  return addr.length > 0 ? addr : from.trim().toLowerCase();
-}
-
-function unavailable(error: string): ProviderPollResult {
-  return { items: [], state: 'unavailable', error };
-}
-
-function errMsg(error: unknown): string {
-  return summarizeError(error);
-}