@kodelyth/discord 2026.5.39 → 2026.5.42

package/src/shared-interactive.ts

@@ -0,0 +1,161 @@
+import { reduceInteractiveReply } from "klaw/plugin-sdk/interactive-runtime";
+import type {
+  InteractiveButtonStyle,
+  InteractiveReply,
+  MessagePresentation,
+  MessagePresentationButton,
+} from "klaw/plugin-sdk/interactive-runtime";
+import type {
+  DiscordComponentButtonSpec,
+  DiscordComponentButtonStyle,
+  DiscordComponentMessageSpec,
+} from "./components.types.js";
+
+function resolveDiscordInteractiveButtonStyle(
+  style?: InteractiveButtonStyle,
+): DiscordComponentButtonStyle | undefined {
+  return style ?? "secondary";
+}
+
+const DISCORD_INTERACTIVE_BUTTON_ROW_SIZE = 5;
+
+/**
+ * @deprecated Use buildDiscordPresentationComponents with MessagePresentation.
+ */
+export function buildDiscordInteractiveComponents(
+  interactive?: InteractiveReply,
+): DiscordComponentMessageSpec | undefined {
+  const blocks = reduceInteractiveReply(
+    interactive,
+    [] as NonNullable<DiscordComponentMessageSpec["blocks"]>,
+    (state, block) => {
+      if (block.type === "text") {
+        const text = block.text.trim();
+        if (text) {
+          state.push({ type: "text", text });
+        }
+        return state;
+      }
+      if (block.type === "buttons") {
+        if (block.buttons.length === 0) {
+          return state;
+        }
+        for (
+          let index = 0;
+          index < block.buttons.length;
+          index += DISCORD_INTERACTIVE_BUTTON_ROW_SIZE
+        ) {
+          state.push({
+            type: "actions",
+            buttons: block.buttons
+              .slice(index, index + DISCORD_INTERACTIVE_BUTTON_ROW_SIZE)
+              .map((button) => {
+                const spec: DiscordComponentButtonSpec = {
+                  label: button.label,
+                  style: button.url ? "link" : resolveDiscordInteractiveButtonStyle(button.style),
+                };
+                if (button.value) {
+                  spec.callbackData = button.value;
+                }
+                if (button.url) {
+                  spec.url = button.url;
+                }
+                return spec;
+              }),
+          });
+        }
+        return state;
+      }
+      if (block.type === "select" && block.options.length > 0) {
+        state.push({
+          type: "actions",
+          select: {
+            type: "string",
+            placeholder: block.placeholder,
+            options: block.options.map((option) => ({
+              label: option.label,
+              value: option.value,
+            })),
+          },
+        });
+      }
+      return state;
+    },
+  );
+  return blocks.length > 0 ? { blocks } : undefined;
+}
+
+export function buildDiscordPresentationComponents(
+  presentation?: MessagePresentation,
+): DiscordComponentMessageSpec | undefined {
+  if (!presentation) {
+    return undefined;
+  }
+  const spec: DiscordComponentMessageSpec = { blocks: [] };
+  if (presentation.title) {
+    spec.blocks?.push({ type: "text", text: presentation.title });
+  }
+  for (const block of presentation.blocks) {
+    if (block.type === "text" || block.type === "context") {
+      const text = block.text.trim();
+      if (text) {
+        spec.blocks?.push({
+          type: "text",
+          text: block.type === "context" ? `-# ${text}` : text,
+        });
+      }
+      continue;
+    }
+    if (block.type === "divider") {
+      spec.blocks?.push({ type: "separator" });
+      continue;
+    }
+  }
+  for (const block of presentation.blocks) {
+    if (block.type === "buttons") {
+      appendDiscordPresentationButtonBlocks(spec, block.buttons);
+      continue;
+    }
+    if (block.type === "select" && block.options.length > 0) {
+      spec.blocks?.push({
+        type: "actions",
+        select: {
+          type: "string",
+          placeholder: block.placeholder,
+          options: block.options.map((option) => ({
+            label: option.label,
+            value: option.value,
+          })),
+        },
+      });
+    }
+  }
+  return spec.blocks?.length ? spec : undefined;
+}
+
+function appendDiscordPresentationButtonBlocks(
+  spec: DiscordComponentMessageSpec,
+  buttons: readonly MessagePresentationButton[],
+) {
+  if (buttons.length === 0) {
+    return;
+  }
+  for (let index = 0; index < buttons.length; index += DISCORD_INTERACTIVE_BUTTON_ROW_SIZE) {
+    spec.blocks?.push({
+      type: "actions",
+      buttons: buttons.slice(index, index + DISCORD_INTERACTIVE_BUTTON_ROW_SIZE).map((button) => {
+        const component: DiscordComponentButtonSpec = {
+          label: button.label,
+          style: button.url ? "link" : resolveDiscordInteractiveButtonStyle(button.style),
+        };
+        if (button.value) {
+          component.callbackData = button.value;
+        }
+        if (button.url) {
+          component.url = button.url;
+        }
+        return component;
+      }),
+    });
+  }
+}

package/src/shared.test.ts

@@ -0,0 +1,186 @@
+import type { KlawConfig } from "klaw/plugin-sdk/config-contracts";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createDiscordPluginBase, discordConfigAdapter } from "./shared.js";
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+});
+
+describe("createDiscordPluginBase", () => {
+  it("owns Discord native command name overrides", () => {
+    const plugin = createDiscordPluginBase({ setup: {} as never });
+
+    expect(
+      plugin.commands?.resolveNativeCommandName?.({
+        commandKey: "tts",
+        defaultName: "tts",
+      }),
+    ).toBe("voice");
+    expect(
+      plugin.commands?.resolveNativeCommandName?.({
+        commandKey: "status",
+        defaultName: "status",
+      }),
+    ).toBe("status");
+  });
+
+  it("exposes security checks on the setup surface", () => {
+    const plugin = createDiscordPluginBase({ setup: {} as never });
+
+    expect(plugin.security?.resolveDmPolicy).toBeTypeOf("function");
+    expect(plugin.security?.collectWarnings).toBeTypeOf("function");
+    expect(plugin.security?.collectAuditFindings).toBeTypeOf("function");
+  });
+
+  it("hydrates announce delivery targets from stored session routing", () => {
+    const plugin = createDiscordPluginBase({ setup: {} as never });
+
+    expect(plugin.meta.preferSessionLookupForAnnounceTarget).toBe(true);
+  });
+
+  it("reports duplicate-token accounts as disabled to gateway startup", () => {
+    vi.stubEnv("DISCORD_BOT_TOKEN", "same-token");
+    const plugin = createDiscordPluginBase({ setup: {} as never });
+    const cfg = {
+      channels: {
+        discord: {
+          accounts: {
+            work: {
+              token: "same-token",
+            },
+          },
+        },
+      },
+    };
+
+    const defaultAccount = plugin.config.resolveAccount(cfg, "default");
+    const workAccount = plugin.config.resolveAccount(cfg, "work");
+
+    expect(plugin.config.isEnabled?.(defaultAccount, cfg)).toBe(false);
+    expect(plugin.config.disabledReason?.(defaultAccount, cfg)).toBe(
+      'duplicate bot token; using account "work"',
+    );
+    expect(plugin.config.isEnabled?.(workAccount, cfg)).toBe(true);
+  });
+
+  it("describes unresolved SecretRef tokens as startup-configured so startup reports the resolver error", () => {
+    const plugin = createDiscordPluginBase({ setup: {} as never });
+    const cfg = {
+      channels: {
+        discord: {
+          token: { source: "env", provider: "default", id: "DISCORD_BOT_TOKEN" },
+        },
+      },
+    } as unknown as KlawConfig;
+
+    const account = plugin.config.resolveAccount(cfg, "default");
+    const described = plugin.config.describeAccount?.(account, cfg);
+
+    expect(account.token).toBe("");
+    expect(account.tokenSource).toBe("config");
+    expect(account.tokenStatus).toBe("configured_unavailable");
+    expect(plugin.config.isConfigured?.(account, cfg)).toBe(true);
+    expect(described?.configured).toBe(true);
+    expect(described?.tokenStatus).toBe("configured_unavailable");
+  });
+});
+
+describe("discordConfigAdapter", () => {
+  it("resolves top-level allowFrom before legacy dm.allowFrom", () => {
+    const cfg = {
+      channels: {
+        discord: {
+          accounts: {
+            default: {
+              allowFrom: ["123"],
+              dm: { allowFrom: ["456"] },
+            },
+          },
+        },
+      },
+    } as KlawConfig;
+
+    expect(discordConfigAdapter.resolveAllowFrom?.({ cfg, accountId: "default" })).toEqual(["123"]);
+  });
+
+  it("falls back to legacy dm.allowFrom", () => {
+    const cfg = {
+      channels: {
+        discord: {
+          accounts: {
+            default: {
+              dm: { allowFrom: ["456"] },
+            },
+          },
+        },
+      },
+    } as KlawConfig;
+
+    expect(discordConfigAdapter.resolveAllowFrom?.({ cfg, accountId: "default" })).toEqual(["456"]);
+  });
+
+  it("prefers account legacy dm.allowFrom over inherited root allowFrom", () => {
+    const cfg = {
+      channels: {
+        discord: {
+          allowFrom: ["root"],
+          accounts: {
+            work: {
+              dm: { allowFrom: ["account-legacy"] },
+            },
+          },
+        },
+      },
+    } as KlawConfig;
+
+    expect(discordConfigAdapter.resolveAllowFrom?.({ cfg, accountId: "work" })).toEqual([
+      "account-legacy",
+    ]);
+  });
+
+  it("coerces numeric allowFrom entries at the config boundary", () => {
+    const cfg = {
+      channels: {
+        discord: {
+          accounts: {
+            default: {
+              allowFrom: [123456789],
+            },
+          },
+        },
+      },
+    } as unknown as KlawConfig;
+
+    expect(discordConfigAdapter.resolveAllowFrom?.({ cfg, accountId: "default" })).toEqual([
+      "123456789",
+    ]);
+  });
+
+  it("keeps read-only accessors from resolving token SecretRefs", () => {
+    const cfg = {
+      secrets: {
+        providers: {
+          discord_token: {
+            source: "file",
+            path: "/tmp/klaw-missing-discord-token",
+            mode: "singleValue",
+          },
+        },
+      },
+      channels: {
+        discord: {
+          token: { source: "file", provider: "discord_token", id: "value" },
+          allowFrom: ["1128540374256849009"],
+          defaultTo: "1498959610751750304",
+        },
+      },
+    } as KlawConfig;
+
+    expect(discordConfigAdapter.resolveAllowFrom?.({ cfg, accountId: "default" })).toEqual([
+      "1128540374256849009",
+    ]);
+    expect(discordConfigAdapter.resolveDefaultTo?.({ cfg, accountId: "default" })).toBe(
+      "1498959610751750304",
+    );
+  });
+});

package/src/shared.ts

@@ -0,0 +1,197 @@
+import { describeAccountSnapshot } from "klaw/plugin-sdk/account-helpers";
+import { normalizeAccountId } from "klaw/plugin-sdk/account-id";
+import { formatAllowFromLowercase } from "klaw/plugin-sdk/allow-from";
+import { adaptScopedAccountAccessor } from "klaw/plugin-sdk/channel-config-helpers";
+import { createScopedChannelConfigAdapter } from "klaw/plugin-sdk/channel-config-helpers";
+import type { ChannelDoctorAdapter } from "klaw/plugin-sdk/channel-contract";
+import { inspectDiscordAccount } from "./account-inspect.js";
+import {
+  isDiscordAccountEnabledForRuntime,
+  listDiscordAccountIds,
+  mergeDiscordAccountConfig,
+  resolveDefaultDiscordAccountId,
+  resolveDiscordAccount,
+  resolveDiscordAccountAllowFrom,
+  resolveDiscordAccountDisabledReason,
+  type ResolvedDiscordAccount,
+} from "./accounts.js";
+import {
+  getChatChannelMeta,
+  resolveConfiguredFromCredentialStatuses,
+  type ChannelPlugin,
+} from "./channel-api.js";
+import { DiscordChannelConfigSchema } from "./config-schema.js";
+import { normalizeCompatibilityConfig } from "./doctor-contract.js";
+import { DISCORD_LEGACY_CONFIG_RULES } from "./doctor-shared.js";
+import type { KlawConfig } from "./runtime-api.js";
+import {
+  collectRuntimeConfigAssignments,
+  secretTargetRegistryEntries,
+} from "./secret-config-contract.js";
+import {
+  collectUnsupportedSecretRefConfigCandidates,
+  unsupportedSecretRefSurfacePatterns,
+} from "./security-contract.js";
+import { discordSecurityAdapter } from "./security.js";
+import { deriveLegacySessionChatType } from "./session-contract.js";
+
+const DISCORD_CHANNEL = "discord" as const;
+
+type DiscordDoctorModule = typeof import("./doctor.js");
+type DiscordConfigAccessorAccount = {
+  allowFrom: string[] | undefined;
+  defaultTo: string | undefined;
+};
+
+let discordDoctorModulePromise: Promise<DiscordDoctorModule> | undefined;
+
+async function loadDiscordDoctorModule(): Promise<DiscordDoctorModule> {
+  discordDoctorModulePromise ??= import("./doctor.js");
+  return await discordDoctorModulePromise;
+}
+
+const discordDoctor: ChannelDoctorAdapter = {
+  dmAllowFromMode: "topOnly",
+  groupModel: "route",
+  groupAllowFromFallbackToAllowFrom: false,
+  warnOnEmptyGroupSenderAllowlist: false,
+  legacyConfigRules: DISCORD_LEGACY_CONFIG_RULES,
+  normalizeCompatibilityConfig,
+  collectPreviewWarnings: async (params) =>
+    (await loadDiscordDoctorModule()).discordDoctor.collectPreviewWarnings?.(params) ?? [],
+  collectMutableAllowlistWarnings: async (params) =>
+    (await loadDiscordDoctorModule()).discordDoctor.collectMutableAllowlistWarnings?.(params) ?? [],
+  repairConfig: async (params) =>
+    (await loadDiscordDoctorModule()).discordDoctor.repairConfig?.(params) ?? {
+      config: params.cfg,
+      changes: [],
+    },
+};
+
+function resolveDiscordConfigAccessorAccount(params: {
+  cfg: KlawConfig;
+  accountId?: string | null;
+}): DiscordConfigAccessorAccount {
+  const accountId = normalizeAccountId(
+    params.accountId ?? resolveDefaultDiscordAccountId(params.cfg),
+  );
+  const config = mergeDiscordAccountConfig(params.cfg, accountId);
+  return {
+    allowFrom: resolveDiscordAccountAllowFrom({ cfg: params.cfg, accountId }),
+    defaultTo: config.defaultTo,
+  };
+}
+
+export const discordConfigAdapter = createScopedChannelConfigAdapter<
+  ResolvedDiscordAccount,
+  DiscordConfigAccessorAccount
+>({
+  sectionKey: DISCORD_CHANNEL,
+  listAccountIds: listDiscordAccountIds,
+  resolveAccount: adaptScopedAccountAccessor(resolveDiscordAccount),
+  resolveAccessorAccount: resolveDiscordConfigAccessorAccount,
+  inspectAccount: adaptScopedAccountAccessor(inspectDiscordAccount),
+  defaultAccountId: resolveDefaultDiscordAccountId,
+  clearBaseFields: ["token", "name"],
+  resolveAllowFrom: (account) => account.allowFrom,
+  formatAllowFrom: (allowFrom) => formatAllowFromLowercase({ allowFrom }),
+  resolveDefaultTo: (account) => account.defaultTo,
+});
+
+export function createDiscordPluginBase(params: {
+  setup: NonNullable<ChannelPlugin<ResolvedDiscordAccount>["setup"]>;
+  setupWizard?: ChannelPlugin<ResolvedDiscordAccount>["setupWizard"];
+}): Pick<
+  ChannelPlugin<ResolvedDiscordAccount>,
+  | "id"
+  | "meta"
+  | "setupWizard"
+  | "capabilities"
+  | "commands"
+  | "doctor"
+  | "streaming"
+  | "reload"
+  | "configSchema"
+  | "config"
+  | "setup"
+  | "messaging"
+  | "security"
+  | "secrets"
+> {
+  return {
+    id: DISCORD_CHANNEL,
+    ...(params.setupWizard ? { setupWizard: params.setupWizard } : {}),
+    meta: { ...getChatChannelMeta(DISCORD_CHANNEL) },
+    capabilities: {
+      chatTypes: ["direct", "channel", "thread"],
+      polls: true,
+      reactions: true,
+      threads: true,
+      media: true,
+      tts: {
+        voice: {
+          synthesisTarget: "voice-note",
+        },
+      },
+      nativeCommands: true,
+    },
+    commands: {
+      nativeCommandsAutoEnabled: true,
+      nativeSkillsAutoEnabled: true,
+      resolveNativeCommandName: ({ commandKey, defaultName }) =>
+        commandKey === "tts" ? "voice" : defaultName,
+    },
+    doctor: discordDoctor,
+    streaming: {
+      blockStreamingCoalesceDefaults: { minChars: 1500, idleMs: 1000 },
+    },
+    reload: { configPrefixes: ["channels.discord"] },
+    configSchema: DiscordChannelConfigSchema,
+    config: {
+      ...discordConfigAdapter,
+      hasConfiguredState: ({ env }) =>
+        typeof env?.DISCORD_BOT_TOKEN === "string" && env.DISCORD_BOT_TOKEN.trim().length > 0,
+      isEnabled: (account, cfg) => isDiscordAccountEnabledForRuntime(account, cfg),
+      disabledReason: (account, cfg) => resolveDiscordAccountDisabledReason(account, cfg),
+      isConfigured: (account) =>
+        resolveConfiguredFromCredentialStatuses(account) ?? Boolean(account.token?.trim()),
+      describeAccount: (account) =>
+        describeAccountSnapshot({
+          account,
+          configured:
+            resolveConfiguredFromCredentialStatuses(account) ?? Boolean(account.token?.trim()),
+          extra: {
+            tokenSource: account.tokenSource,
+            tokenStatus: account.tokenStatus,
+          },
+        }),
+    },
+    messaging: {
+      deriveLegacySessionChatType,
+    },
+    security: discordSecurityAdapter,
+    secrets: {
+      secretTargetRegistryEntries,
+      unsupportedSecretRefSurfacePatterns,
+      collectUnsupportedSecretRefConfigCandidates,
+      collectRuntimeConfigAssignments,
+    },
+    setup: params.setup,
+  } as Pick<
+    ChannelPlugin<ResolvedDiscordAccount>,
+    | "id"
+    | "meta"
+    | "setupWizard"
+    | "capabilities"
+    | "commands"
+    | "doctor"
+    | "streaming"
+    | "reload"
+    | "configSchema"
+    | "config"
+    | "setup"
+    | "messaging"
+    | "security"
+    | "secrets"
+  >;
+}

package/src/status-issues.test.ts

@@ -0,0 +1,97 @@
+import type { ChannelAccountSnapshot } from "klaw/plugin-sdk/channel-contract";
+import { describe, expect, it } from "vitest";
+import { collectDiscordStatusIssues } from "./status-issues.js";
+
+describe("collectDiscordStatusIssues", () => {
+  it("reports disabled message content intent and unresolved channel ids", () => {
+    const issues = collectDiscordStatusIssues([
+      {
+        accountId: "ops",
+        enabled: true,
+        configured: true,
+        application: {
+          intents: {
+            messageContent: "disabled",
+          },
+        },
+        audit: {
+          unresolvedChannels: 2,
+        },
+      } as ChannelAccountSnapshot,
+    ]);
+
+    expect(issues).toEqual([
+      {
+        channel: "discord",
+        accountId: "ops",
+        kind: "intent",
+        message: "Message Content Intent is disabled. Bot may not see normal channel messages.",
+        fix: "Enable Message Content Intent in Discord Dev Portal → Bot → Privileged Gateway Intents, or require mention-only operation.",
+      },
+      {
+        channel: "discord",
+        accountId: "ops",
+        kind: "config",
+        message:
+          "Some configured guild channels are not numeric IDs (unresolvedChannels=2). Permission audit can only check numeric channel IDs.",
+        fix: "Use numeric channel IDs as keys in channels.discord.guilds.*.channels (then rerun channels status --probe).",
+      },
+    ]);
+  });
+
+  it("reports channel permission failures with match metadata", () => {
+    const issues = collectDiscordStatusIssues([
+      {
+        accountId: "ops",
+        enabled: true,
+        configured: true,
+        audit: {
+          channels: [
+            {
+              channelId: "123",
+              ok: false,
+              missing: ["ViewChannel", "SendMessages"],
+              error: "403",
+              matchKey: "alerts",
+              matchSource: "guilds.ops.channels",
+            },
+          ],
+        },
+      } as ChannelAccountSnapshot,
+    ]);
+
+    expect(issues).toEqual([
+      {
+        channel: "discord",
+        accountId: "ops",
+        kind: "permissions",
+        message:
+          "Channel 123 permission check failed. missing ViewChannel, SendMessages: 403 (matchKey=alerts matchSource=guilds.ops.channels)",
+        fix: "Ensure the bot role can view + send in this channel (and that channel overrides don't deny it).",
+      },
+    ]);
+  });
+
+  it("reports degraded runtime transport state", () => {
+    const issues = collectDiscordStatusIssues([
+      {
+        accountId: "ops",
+        enabled: true,
+        configured: true,
+        running: true,
+        connected: true,
+        healthState: "stale-socket",
+      } as ChannelAccountSnapshot,
+    ]);
+
+    expect(issues).toEqual([
+      {
+        channel: "discord",
+        accountId: "ops",
+        kind: "runtime",
+        message: "Discord gateway transport is degraded (stale-socket; account is running).",
+        fix: "Check gateway event-loop health and Discord connectivity, then restart the Discord channel or gateway if the transport does not recover.",
+      },
+    ]);
+  });
+});