@pellux/goodvibes-tui 1.27.1 → 2.0.1

package/src/daemon/handlers/triage/tagger/index.ts

@@ -1,184 +0,0 @@
-// ---------------------------------------------------------------------------
-// Daemon-internal triage TAGGER (composition).
-//
-// Applies user-defined triage labels back on the provider side:
-//   - IMAP : STORE a keyword flag on the message (IMAP4rev1 over TLS).
-//   - Slack: reactions.add emoji on the source message.
-//   - Discord: real forum thread tags (PATCH applied_tags, merge) when a
-//     forum-tag mapping is configured, else a unicode reaction analog.
-//
-// Hard rules honored here:
-//   - All provider credentials come ONLY from the daemon credential store.
-//     They are never returned in results and never logged.
-//   - The whole tagger is gated behind a config flag (surfaces.triage.autoTag);
-//     when disabled, applyTags() is a no-op that reports skipped:true.
-//   - Provider-side writes are EFFECTFUL; callers must pass an explicitly
-//     confirmed request (confirm === true && explicitUserRequest === true).
-//     Unconfirmed calls throw HandlerError(REQUIRE_CONFIRM).
-//
-// Contract-fidelity note: the triage surface (`inbox.triage.*`) is daemon-
-// internal and NOT a published operator method, so there is no external
-// request/response schema to certify these tag shapes against. What is
-// guaranteed is the provider-side behavior: no silent data loss (Discord thread
-// tags are merged, never blindly overwritten) and no command injection (IMAP
-// quoting rejects control characters).
-// ---------------------------------------------------------------------------
-
-import type { HandlerContext } from '../../context.ts';
-import type { DaemonCredentialStore } from '../../credentials.ts';
-import { HandlerError, REQUIRE_CONFIRM } from '../../errors.ts';
-import { labelToTag } from '../scorer.ts';
-import { applyImap, imapStoreFlagOverTls, makeRetryingImapStoreFlag } from './imap.ts';
-import type { ImapRetryOptions, ImapStoreFlag } from './imap.ts';
-import { applySlack } from './slack.ts';
-import { applyDiscord } from './discord.ts';
-import type { ApplyTagsRequest, ApplyTagsResult, TaggerProviderConfig } from './shared.ts';
-
-export type {
-  ApplyTagsRequest,
-  ApplyTagsResult,
-  TaggerProviderConfig,
-} from './shared.ts';
-export type { ImapRetryOptions, ImapStoreArgs, ImapStoreFlag } from './imap.ts';
-
-export const TRIAGE_AUTOTAG_FLAG = 'surfaces.triage.autoTag';
-
-export interface TriageTaggerOptions {
-  credentials?: DaemonCredentialStore;
-  /** Override the autotag flag lookup (used in tests). */
-  autoTagEnabled?: boolean;
-  /** Per-surface provider config; usually derived from configManager. */
-  providers?: TaggerProviderConfig;
-  /** Injectable fetch (Slack/Discord HTTP). Defaults to global fetch. */
-  fetchImpl?: typeof fetch;
-  /** Injectable IMAP flag-setter (used in tests to avoid a live socket). */
-  imapStoreFlag?: ImapStoreFlag;
-  /**
-   * Transient-failure retry policy for the default IMAP store implementation.
-   * Ignored when imapStoreFlag is injected and succeeds first-try.
-   */
-  imapRetry?: ImapRetryOptions;
-}
-
-export interface TriageTagger {
-  /** Whether provider-side tagging is currently enabled. */
-  enabled(): boolean;
-  applyTags(request: ApplyTagsRequest): Promise<ApplyTagsResult>;
-}
-
-function readBoolFlag(
-  configManager: HandlerContext['configManager'],
-  key: string,
-): boolean {
-  try {
-    const value = configManager.get(key as never) as unknown;
-    return value === true || value === 'true' || value === 1;
-  } catch {
-    return false;
-  }
-}
-
-function safeGet(configManager: HandlerContext['configManager'], key: string): unknown {
-  try {
-    return configManager.get(key as never) as unknown;
-  } catch {
-    return undefined;
-  }
-}
-
-function resolveProvidersFromConfig(
-  configManager: HandlerContext['configManager'],
-): TaggerProviderConfig {
-  const out: TaggerProviderConfig = {};
-  const slackToken = safeGet(configManager, 'surfaces.slack.botToken');
-  if (typeof slackToken === 'string' && slackToken.length > 0) {
-    out.slack = { tokenConfigKey: 'surfaces.slack.botToken' };
-  }
-  const discordToken = safeGet(configManager, 'surfaces.discord.botToken');
-  if (typeof discordToken === 'string' && discordToken.length > 0) {
-    out.discord = { tokenConfigKey: 'surfaces.discord.botToken' };
-  }
-  const imapHost = safeGet(configManager, 'surfaces.email.imap.host');
-  const imapUser = safeGet(configManager, 'surfaces.email.imap.user');
-  if (typeof imapHost === 'string' && imapHost.length > 0 && typeof imapUser === 'string') {
-    const portRaw = safeGet(configManager, 'surfaces.email.imap.port');
-    const mailbox = safeGet(configManager, 'surfaces.email.imap.mailbox');
-    out.imap = {
-      host: imapHost,
-      port: typeof portRaw === 'number' ? portRaw : 993,
-      user: imapUser,
-      passwordConfigKey: 'surfaces.email.imap.password',
-      mailbox: typeof mailbox === 'string' && mailbox.length > 0 ? mailbox : 'INBOX',
-    };
-  }
-  return out;
-}
-
-function resolveTags(request: ApplyTagsRequest): string[] {
-  if (request.tags && request.tags.length > 0) {
-    return [...new Set(request.tags.map((t) => t.trim()).filter((t) => t.length > 0))];
-  }
-  if (request.label) return [labelToTag(request.label)];
-  return [];
-}
-
-/**
- * Create the triage tagger. Reads the autotag flag and provider config from the
- * handler context; credentials are resolved lazily, per apply, from the daemon
- * credential store.
- */
-export function createTriageTagger(
-  ctx: HandlerContext,
-  options: TriageTaggerOptions = {},
-): TriageTagger {
-  const credentials = options.credentials ?? ctx.credentials;
-  const fetchImpl = options.fetchImpl ?? fetch;
-  const providers = options.providers ?? resolveProvidersFromConfig(ctx.configManager);
-  // Retry wraps whichever store impl is in use (default TLS client OR an
-  // injected one), so transient failures are retried uniformly.
-  const imapStoreFlag = makeRetryingImapStoreFlag(
-    options.imapStoreFlag ?? imapStoreFlagOverTls,
-    options.imapRetry,
-  );
-  const enabled = (): boolean =>
-    options.autoTagEnabled ?? readBoolFlag(ctx.configManager, TRIAGE_AUTOTAG_FLAG);
-
-  return {
-    enabled,
-    async applyTags(request: ApplyTagsRequest): Promise<ApplyTagsResult> {
-      const { item } = request;
-      const tags = resolveTags(request);
-      const base: ApplyTagsResult = {
-        surface: item.surface,
-        itemId: item.id,
-        appliedTags: [],
-        skipped: true,
-      };
-
-      if (!enabled()) {
-        return { ...base, reason: 'autotag-disabled' };
-      }
-
-      // Provider-side mutation is effectful — require explicit confirmation.
-      if (request.confirm !== true || request.explicitUserRequest !== true) {
-        throw new HandlerError(
-          'Provider-side triage tagging requires explicit user confirmation.',
-          REQUIRE_CONFIRM,
-          403,
-        );
-      }
-
-      switch (item.surface) {
-        case 'email':
-        case 'imap':
-          return applyImap(item, tags, providers, credentials, imapStoreFlag, base);
-        case 'slack':
-          return applySlack(item, tags, providers, credentials, fetchImpl, ctx, base);
-        case 'discord':
-          return applyDiscord(item, tags, providers, credentials, fetchImpl, ctx, base);
-        default:
-          return { ...base, reason: `unsupported-surface:${item.surface}` };
-      }
-    },
-  };
-}

package/src/daemon/handlers/triage/tagger/shared.ts

@@ -1,70 +0,0 @@
-// ---------------------------------------------------------------------------
-// Triage tagger — shared types and provider-agnostic helpers.
-//
-// Provider config shapes, the apply request/result contract, and the tag
-// normalization helpers used by the IMAP/Slack/Discord modules. No I/O here.
-// ---------------------------------------------------------------------------
-
-import type { InboundChannelItem, TriageLabel } from '../types.ts';
-
-export interface TaggerProviderConfig {
-  /** IMAP host:port (default port 993, TLS). Credentials resolved separately. */
-  imap?: { host: string; port?: number; user: string; passwordConfigKey: string; mailbox?: string };
-  /** Slack bot token config key (resolved from credential store). */
-  slack?: { tokenConfigKey: string };
-  /**
-   * Discord bot token config key (resolved from credential store), plus an
-   * optional forum-tag mapping. When `forumTagIds` maps a GoodVibes triage tag
-   * (e.g. 'GoodVibes/Spam') to a forum tag SNOWFLAKE id, items that target a
-   * forum/media-channel thread get that REAL thread tag applied (PATCH
-   * applied_tags) — exact fidelity to the contract's "Discord thread tags".
-   * Without a mapping (or for non-thread messages) tagging degrades to a
-   * unicode reaction analog.
-   */
-  discord?: { tokenConfigKey: string; forumTagIds?: Record<string, string> };
-}
-
-export interface ApplyTagsRequest {
-  item: InboundChannelItem;
-  /** Provider-side tags to apply. Defaults to [labelToTag(label)] when omitted. */
-  tags?: readonly string[];
-  label?: TriageLabel;
-  /** Must be true — provider-side mutation requires explicit confirmation. */
-  confirm?: boolean;
-  /** Mirror of the operator invocation context flag. */
-  explicitUserRequest?: boolean;
-}
-
-export interface ApplyTagsResult {
-  surface: string;
-  itemId: string;
-  appliedTags: string[];
-  /** True when the autotag flag is disabled or no provider matched. */
-  skipped: boolean;
-  reason?: string;
-}
-
-/** IMAP keywords cannot contain spaces or '/'; normalize the canonical tag. */
-export function imapKeywordForTag(tag: string): string {
-  return tag.replace(/[^A-Za-z0-9_]+/g, '_');
-}
-
-export function slackEmojiForTag(tag: string): string {
-  const lower = tag.toLowerCase();
-  if (lower.includes('spam')) return 'no_entry_sign';
-  if (lower.includes('priority')) return 'rotating_light';
-  return 'inbox_tray';
-}
-
-export function discordEmojiForTag(tag: string): string {
-  const lower = tag.toLowerCase();
-  if (lower.includes('spam')) return '\u{1F6AB}';
-  if (lower.includes('priority')) return '\u{1F6A8}';
-  return '\u{1F4E5}';
-}
-
-/** Read a non-empty string from the item's opaque metadata bag. */
-export function stringMeta(item: InboundChannelItem, key: string): string | undefined {
-  const value = item.metadata?.[key];
-  return typeof value === 'string' && value.length > 0 ? value : undefined;
-}

package/src/daemon/handlers/triage/tagger/slack.ts

@@ -1,69 +0,0 @@
-// ---------------------------------------------------------------------------
-// Triage tagger — Slack provider.
-//
-// Applies a triage label as a Slack message reaction (reactions.add). The bot
-// token is resolved per-apply from the daemon credential store and is never
-// logged or returned. `already_reacted` is treated as idempotent success.
-// ---------------------------------------------------------------------------
-
-import type { HandlerContext } from '../../context.ts';
-import type { DaemonCredentialStore } from '../../credentials.ts';
-import { HandlerError } from '../../errors.ts';
-import type { InboundChannelItem } from '../types.ts';
-import type { ApplyTagsResult, TaggerProviderConfig } from './shared.ts';
-import { slackEmojiForTag, stringMeta } from './shared.ts';
-
-export async function applySlack(
-  item: InboundChannelItem,
-  tags: string[],
-  providers: TaggerProviderConfig,
-  credentials: DaemonCredentialStore,
-  fetchImpl: typeof fetch,
-  ctx: HandlerContext,
-  base: ApplyTagsResult,
-): Promise<ApplyTagsResult> {
-  const cfg = providers.slack;
-  if (!cfg) return { ...base, reason: 'slack-not-configured' };
-  const channel = stringMeta(item, 'channelId') ?? item.conversationId;
-  const ts = stringMeta(item, 'ts') ?? stringMeta(item, 'messageTs');
-  if (!channel || !ts) return { ...base, reason: 'slack-missing-target' };
-  if (tags.length === 0) return { ...base, reason: 'no-tags' };
-
-  const token = await credentials.resolveConfigSecret(cfg.tokenConfigKey);
-  if (!token) return { ...base, reason: 'slack-no-credentials' };
-
-  const applied: string[] = [];
-  for (const tag of tags) {
-    const emoji = slackEmojiForTag(tag);
-    const response = await fetchImpl('https://slack.com/api/reactions.add', {
-      method: 'POST',
-      headers: {
-        Authorization: `Bearer ${token}`,
-        'Content-Type': 'application/json; charset=utf-8',
-      },
-      body: JSON.stringify({ channel, timestamp: ts, name: emoji }),
-    });
-    const payload = (await response.json().catch(() => ({}))) as {
-      ok?: boolean;
-      error?: string;
-    };
-    if (!response.ok) {
-      throw new HandlerError(
-        `Slack reactions.add HTTP ${response.status}`,
-        'TRIAGE_SLACK_TAG_FAILED',
-        502,
-      );
-    }
-    // 'already_reacted' is an idempotent success for our purposes.
-    if (payload.ok !== true && payload.error !== 'already_reacted') {
-      ctx.logger.warn('triage: slack reaction rejected', { error: payload.error });
-      throw new HandlerError(
-        `Slack reactions.add rejected: ${payload.error ?? 'unknown'}`,
-        'TRIAGE_SLACK_TAG_FAILED',
-        502,
-      );
-    }
-    applied.push(tag);
-  }
-  return { surface: item.surface, itemId: item.id, appliedTags: applied, skipped: false };
-}

package/src/daemon/handlers/triage/types.ts

@@ -1,50 +0,0 @@
-// ---------------------------------------------------------------------------
-// Daemon-internal triage domain types.
-//
-// `InboundChannelItem` is the daemon-internal shape the inbox poller produces
-// and the triage pipeline scores. It is NOT an SDK catalog contract: the
-// published `channels.inbox.list` output schema (CHANNEL_INBOX_ITEM_SCHEMA) is
-// owned by the SDK and never re-declared here. This is the internal poller
-// item per the handoff doc — it carries `fromDigest` (never a raw sender id),
-// `subjectPreview`/`bodyPreview` (PII-stripped, length-bounded) and an opaque
-// `metadata` bag the tagger reads provider targeting from (imapUid, channelId,
-// Slack ts, Discord messageId/threadId).
-// ---------------------------------------------------------------------------
-
-/** Triage label assigned by the scorer. */
-export type TriageLabel = 'spam' | 'priority' | 'normal';
-
-/** 1:1 vs group/channel/thread conversation hint (priority signal). */
-export type ConversationKind = 'direct' | 'group' | 'channel' | 'thread' | 'service';
-
-/**
- * Internal inbound feed item. Mirrors the handoff `InboundChannelItem` shape
- * plus the optional fields the scorer/tagger consult. `surface` is the provider
- * family ('email' | 'imap' | 'slack' | 'discord' | ...) the tagger dispatches
- * on; `provider` is the handoff-facing provider id. They are usually equal.
- */
-export interface InboundChannelItem {
-  /** Stable, provider-scoped dedup key. */
-  readonly id: string;
-  /** Provider family the tagger dispatches on (email/imap/slack/discord/...). */
-  readonly surface: string;
-  /** Handoff-facing provider id ("slack" | "discord" | "email" | ...). */
-  readonly provider?: string;
-  readonly kind?: 'dm' | 'thread' | 'mention' | 'reaction';
-  /** SHA-256 first-N of sender external id — NEVER a raw identifier. */
-  readonly fromDigest?: string;
-  /** Conversation id (Slack/Discord channel, IMAP mailbox-scoped). */
-  readonly conversationId?: string;
-  readonly conversationKind?: ConversationKind;
-  /** Display subject (<= 200 chars). */
-  readonly subject?: string;
-  /** Display body preview (<= 500 chars, PII-stripped). Alias: bodyPreview. */
-  readonly snippet?: string;
-  /** Optional daemon route binding id. */
-  readonly routeId?: string;
-  /** Unix ms. */
-  readonly receivedAt?: number;
-  readonly unread?: boolean;
-  /** Opaque provider targeting bag (imapUid/uid, channelId, ts, messageId, threadId). */
-  readonly metadata?: Record<string, unknown>;
-}

package/src/daemon/lifecycle.ts

@@ -1,41 +0,0 @@
-/**
- * lifecycle.ts — resolve THIS binary's update-artifact identity for the SDK
- * DaemonServer facade's auto-update lifecycle.
- *
- * The SDK facade now runs the entire self-update loop itself when handed a
- * DaemonUpdateArtifact ({version, execPath}): it compares the HOST binary's
- * version against the release tags (no longer the version-blind sdk-package
- * comparison that used to restart-loop), swaps only at an idle moment, keeps
- * the outgoing file at `<path>.previous`, and leaves a receipt in the store it
- * serves on /status. When the artifact is ABSENT, updates are host-managed —
- * the facade runs no loop (the safe embedded default).
- *
- * The one guard the facade does NOT apply is install-kind: it must never swap a
- * dev `bun run daemon` interpreter or a bun-global package install. This helper
- * is that guard — it hands the facade an artifact ONLY for a compiled binary
- * install, so a dev run resolves to `undefined` (host-managed, no loop) and
- * only a real self-contained binary self-updates.
- */
-import type { DaemonUpdateArtifact } from '@pellux/goodvibes-sdk/platform/daemon';
-import { VERSION } from '../version.ts';
-import { detectInstallKind } from '../runtime/update-check.ts';
-
-export interface ResolveDaemonUpdateArtifactOptions {
-  /** The executable to identify; defaults to process.execPath. */
-  readonly execPath?: string;
-  /** Injectable so tests pin a fixture version — never the live build VERSION. */
-  readonly version?: string;
-}
-
-/**
- * The update-artifact identity to hand the DaemonServer facade, or `undefined`
- * for a non-binary install (dev/source or bun-global package) — in which case
- * the facade keeps updates host-managed and runs no swap loop.
- */
-export function resolveDaemonUpdateArtifact(
-  options: ResolveDaemonUpdateArtifactOptions = {},
-): DaemonUpdateArtifact | undefined {
-  const execPath = options.execPath ?? process.execPath;
-  if (detectInstallKind(execPath) !== 'binary') return undefined;
-  return { version: options.version ?? VERSION, execPath };
-}

package/src/daemon/provision-wake-model.ts

@@ -1,81 +0,0 @@
-// ---------------------------------------------------------------------------
-// provision-wake-model.ts — `goodvibes-daemon provision-wake-model`.
-//
-// WHAT THIS IS FOR
-//
-// The curl installer needs to put the wake-word model on the machine, and it must
-// not hold the pinned URLs, byte counts or checksums to do it. Those live in ONE
-// place — the SDK's wake-word manifest — and a shell script that copied them
-// would be a second copy of a pin, drifting silently the first time the model is
-// retrained. So the installer runs the binary it just installed and lets the SDK
-// do what the SDK owns.
-//
-// IT EXITS 0 EVEN WHEN THE DOWNLOAD FAILS, ON PURPOSE
-//
-// The caller is an installer. A wake-word model is not a reason to fail installing
-// a coding tool, and an installer that aborts half-way through is worse than one
-// that finishes without a wake word. The outcome is printed either way — one plain
-// line naming what happened and how to retry — and a running daemon retries at
-// every boot. `--strict` is there for a caller that genuinely wants the exit code
-// to carry the result (a test, a provisioning script that is checking); the
-// installer does not pass it.
-//
-// It composes NOTHING. No runtime, no config manager, no gateway: this reads a
-// home directory, derives the managed voice root the same way the running daemon
-// does, and calls one SDK function. Composing a runtime here would start a second
-// set of pollers on a machine whose daemon is probably already running.
-// ---------------------------------------------------------------------------
-
-import {
-  provisionWakeWordModelsAtInstall,
-  resolveManagedVoiceRoot,
-} from '@pellux/goodvibes-sdk/platform/voice';
-
-export interface ProvisionWakeModelResult {
-  readonly exitCode: number;
-  readonly lines: readonly string[];
-}
-
-export interface ProvisionWakeModelDeps {
-  /** The home directory whose `.goodvibes/voice` tree receives the artifacts. */
-  readonly homeDirectory: string;
-  readonly env?: Readonly<Record<string, string | undefined>> | undefined;
-  /** Injected in tests: the SDK policy, so nothing downloads. */
-  readonly provisionAtInstall?: typeof provisionWakeWordModelsAtInstall | undefined;
-}
-
-/**
- * Run the install-time provision and report it.
- *
- * `--strict` makes a degraded outcome exit 1. Without it, every outcome exits 0,
- * because the caller is an installer and the alternative is an aborted install
- * over an optional model.
- */
-export async function runProvisionWakeModelCommand(
-  argv: readonly string[],
-  deps: ProvisionWakeModelDeps,
-): Promise<ProvisionWakeModelResult> {
-  const strict = argv.includes('--strict');
-  const provision = deps.provisionAtInstall ?? provisionWakeWordModelsAtInstall;
-  let managedRoot: string;
-  try {
-    managedRoot = resolveManagedVoiceRoot(deps.homeDirectory);
-  } catch (error) {
-    // A home directory this process cannot make sense of is still not a reason to
-    // fail an install, so it is reported on the same terms as a failed download.
-    const message = error instanceof Error ? error.message : String(error);
-    return {
-      exitCode: strict ? 1 : 0,
-      lines: [`wake-word model: skipped — ${message}`],
-    };
-  }
-  const outcome = await provision({
-    managedRoot,
-    recoveryHint: '/voice wake setup',
-    ...(deps.env !== undefined ? { env: deps.env } : {}),
-  });
-  return {
-    exitCode: strict && outcome.state === 'degraded' ? 1 : 0,
-    lines: [`wake-word model: ${outcome.message}`],
-  };
-}

package/src/daemon/safe-serve.ts

@@ -1,61 +0,0 @@
-import { logger } from '@pellux/goodvibes-sdk/platform/utils';
-import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
-
-type HostServeFetch = (
-  request: Request,
-  server: unknown,
-) => Response | undefined | Promise<Response | undefined>;
-
-type HostServeOptions = Parameters<typeof Bun.serve>[0] & {
-  fetch?: HostServeFetch;
-};
-
-function requestPath(request: Request): string {
-  try {
-    return new URL(request.url).pathname;
-  } catch {
-    return request.url;
-  }
-}
-
-export function createHostRequestFailureResponse(
-  surface: string,
-  request: Request,
-  error: unknown,
-): Response {
-  const message = summarizeError(error);
-  logger.error(`${surface}: request handler failed`, {
-    method: request.method,
-    path: requestPath(request),
-    error: message,
-  });
-  return Response.json({
-    error: message,
-    code: 'HOST_REQUEST_HANDLER_FAILED',
-  }, { status: 500 });
-}
-
-export function createSafeHostServeFactory(
-  surface: string,
-  baseServeFactory: typeof Bun.serve = Bun.serve,
-): typeof Bun.serve {
-  return ((options: HostServeOptions) => {
-    const originalFetch = options.fetch;
-    if (typeof originalFetch !== 'function') {
-      return baseServeFactory(options as Parameters<typeof Bun.serve>[0]);
-    }
-
-    const wrappedFetch: HostServeFetch = async (request, server) => {
-      try {
-        return await originalFetch(request, server);
-      } catch (error) {
-        return createHostRequestFailureResponse(surface, request, error);
-      }
-    };
-
-    return baseServeFactory({
-      ...options,
-      fetch: wrappedFetch,
-    } as Parameters<typeof Bun.serve>[0]);
-  }) as typeof Bun.serve;
-}