@kodelyth/discord 2026.5.39 → 2026.5.42

package/src/setup-adapter.ts

@@ -0,0 +1,14 @@
+import {
+  createEnvPatchedAccountSetupAdapter,
+  type ChannelSetupAdapter,
+} from "klaw/plugin-sdk/setup-runtime";
+
+const channel = "discord" as const;
+
+export const discordSetupAdapter: ChannelSetupAdapter = createEnvPatchedAccountSetupAdapter({
+  channelKey: channel,
+  defaultAccountOnlyEnvError: "DISCORD_BOT_TOKEN can only be used for the default account.",
+  missingCredentialError: "Discord requires token (or --use-env).",
+  hasCredentials: (input) => Boolean(input.token),
+  buildPatch: (input) => (input.token ? { token: input.token } : {}),
+});

package/src/setup-core.ts

@@ -0,0 +1,215 @@
+import { DEFAULT_ACCOUNT_ID } from "klaw/plugin-sdk/account-id";
+import type { DiscordGuildEntry, KlawConfig } from "klaw/plugin-sdk/config-contracts";
+import type { ChannelSetupDmPolicy, ChannelSetupWizard } from "klaw/plugin-sdk/setup-runtime";
+import {
+  createSetupTranslator,
+  createStandardChannelSetupStatus,
+} from "klaw/plugin-sdk/setup-runtime";
+import { formatDocsLink } from "klaw/plugin-sdk/setup-tools";
+import { normalizeOptionalString } from "klaw/plugin-sdk/string-coerce-runtime";
+import {
+  inspectDiscordSetupAccount,
+  resolveDiscordSetupAccountConfig,
+} from "./setup-account-state.js";
+import {
+  createAccountScopedAllowFromSection,
+  createAccountScopedGroupAccessSection,
+  createLegacyCompatChannelDmPolicy,
+  parseMentionOrPrefixedId,
+  patchChannelConfigForAccount,
+  setSetupChannelEnabled,
+} from "./setup-runtime-helpers.js";
+
+const t = createSetupTranslator();
+
+const channel = "discord" as const;
+const DISCORD_TOKEN_HELP_LINES = [
+  t("wizard.discord.tokenHelpCreateApplication"),
+  t("wizard.discord.tokenHelpCopyToken"),
+  t("wizard.discord.tokenHelpInviteBot"),
+  t("wizard.discord.tokenHelpMessageContentIntent"),
+  t("wizard.channels.docs", { link: formatDocsLink("/discord", "discord") }),
+];
+
+type DiscordGuildChannelAllowlistEntry = {
+  guildKey: string;
+  channelKey?: string;
+};
+
+type DiscordSetupAllowlistResolution = {
+  resolved?: boolean;
+  guildId?: string;
+  channelId?: string;
+  guildKey?: string;
+  channelKey?: string;
+};
+
+function mapDiscordSetupAllowlistEntries(resolved: unknown): DiscordGuildChannelAllowlistEntry[] {
+  if (!Array.isArray(resolved)) {
+    return [];
+  }
+  return resolved.flatMap((entry): DiscordGuildChannelAllowlistEntry[] => {
+    if (!entry || typeof entry !== "object") {
+      return [];
+    }
+    const row = entry as DiscordSetupAllowlistResolution;
+    if (row.resolved === false) {
+      return [];
+    }
+    const guildKey = normalizeOptionalString(row.guildId ?? row.guildKey);
+    if (!guildKey) {
+      return [];
+    }
+    const channelKey = normalizeOptionalString(row.channelId ?? row.channelKey);
+    return channelKey ? [{ guildKey, channelKey }] : [{ guildKey }];
+  });
+}
+
+function setDiscordGuildChannelAllowlist(
+  cfg: KlawConfig,
+  accountId: string,
+  entries: DiscordGuildChannelAllowlistEntry[],
+): KlawConfig {
+  const baseGuilds =
+    accountId === DEFAULT_ACCOUNT_ID
+      ? (cfg.channels?.discord?.guilds ?? {})
+      : (cfg.channels?.discord?.accounts?.[accountId]?.guilds ?? {});
+  const guilds: Record<string, DiscordGuildEntry> = { ...baseGuilds };
+  for (const entry of entries) {
+    const guildKey = entry.guildKey || "*";
+    const existing = guilds[guildKey] ?? {};
+    if (entry.channelKey) {
+      const channels = { ...existing.channels };
+      channels[entry.channelKey] = { enabled: true };
+      guilds[guildKey] = { ...existing, channels };
+    } else {
+      guilds[guildKey] = existing;
+    }
+  }
+  return patchChannelConfigForAccount({
+    cfg,
+    channel,
+    accountId,
+    patch: { guilds },
+  });
+}
+
+export function parseDiscordAllowFromId(value: string): string | null {
+  return parseMentionOrPrefixedId({
+    value,
+    mentionPattern: /^<@!?(\d+)>$/,
+    prefixPattern: /^(user:|discord:)/i,
+    idPattern: /^\d+$/,
+  });
+}
+
+export function createDiscordSetupWizardBase(handlers: {
+  promptAllowFrom: NonNullable<ChannelSetupDmPolicy["promptAllowFrom"]>;
+  resolveAllowFromEntries: NonNullable<
+    NonNullable<ChannelSetupWizard["allowFrom"]>["resolveEntries"]
+  >;
+  resolveGroupAllowlist: NonNullable<
+    NonNullable<NonNullable<ChannelSetupWizard["groupAccess"]>["resolveAllowlist"]>
+  >;
+}) {
+  const discordDmPolicy: ChannelSetupDmPolicy = createLegacyCompatChannelDmPolicy({
+    label: "Discord",
+    channel,
+    promptAllowFrom: handlers.promptAllowFrom,
+  });
+
+  return {
+    channel,
+    status: createStandardChannelSetupStatus({
+      channelLabel: "Discord",
+      configuredLabel: t("wizard.channels.statusConfigured"),
+      unconfiguredLabel: t("wizard.channels.statusNeedsToken"),
+      configuredHint: t("wizard.channels.statusConfigured"),
+      unconfiguredHint: t("wizard.channels.statusNeedsToken"),
+      configuredScore: 2,
+      unconfiguredScore: 1,
+      resolveConfigured: ({ cfg, accountId }) =>
+        inspectDiscordSetupAccount({ cfg, accountId }).configured,
+    }),
+    credentials: [
+      {
+        inputKey: "token",
+        providerHint: channel,
+        credentialLabel: t("wizard.discord.botToken"),
+        preferredEnvVar: "DISCORD_BOT_TOKEN",
+        helpTitle: t("wizard.discord.botToken"),
+        helpLines: DISCORD_TOKEN_HELP_LINES,
+        envPrompt: t("wizard.discord.tokenEnvPrompt"),
+        keepPrompt: t("wizard.discord.tokenKeepPrompt"),
+        inputPrompt: t("wizard.discord.tokenInputPrompt"),
+        allowEnv: ({ accountId }: { accountId: string }) => accountId === DEFAULT_ACCOUNT_ID,
+        inspect: ({ cfg, accountId }: { cfg: KlawConfig; accountId: string }) => {
+          const account = inspectDiscordSetupAccount({ cfg, accountId });
+          return {
+            accountConfigured: account.configured,
+            hasConfiguredValue: account.tokenStatus !== "missing",
+            resolvedValue: normalizeOptionalString(account.token),
+            envValue:
+              accountId === DEFAULT_ACCOUNT_ID
+                ? normalizeOptionalString(process.env.DISCORD_BOT_TOKEN)
+                : undefined,
+          };
+        },
+      },
+    ],
+    groupAccess: createAccountScopedGroupAccessSection({
+      channel,
+      label: t("wizard.discord.channelsLabel"),
+      placeholder: "My Server/#general, guildId/channelId, #support",
+      currentPolicy: ({ cfg, accountId }: { cfg: KlawConfig; accountId: string }) =>
+        resolveDiscordSetupAccountConfig({ cfg, accountId }).config.groupPolicy ?? "allowlist",
+      currentEntries: ({ cfg, accountId }: { cfg: KlawConfig; accountId: string }) =>
+        Object.entries(
+          resolveDiscordSetupAccountConfig({ cfg, accountId }).config.guilds ?? {},
+        ).flatMap(([guildKey, value]) => {
+          const channels = value?.channels ?? {};
+          const channelKeys = Object.keys(channels);
+          if (channelKeys.length === 0) {
+            const input = /^\d+$/.test(guildKey) ? `guild:${guildKey}` : guildKey;
+            return [input];
+          }
+          return channelKeys.map((channelKey) => `${guildKey}/${channelKey}`);
+        }),
+      updatePrompt: ({ cfg, accountId }: { cfg: KlawConfig; accountId: string }) =>
+        Boolean(resolveDiscordSetupAccountConfig({ cfg, accountId }).config.guilds),
+      resolveAllowlist: handlers.resolveGroupAllowlist,
+      fallbackResolved: (entries) => entries.map((input) => ({ input, resolved: false })),
+      applyAllowlist: ({
+        cfg,
+        accountId,
+        resolved,
+      }: {
+        cfg: KlawConfig;
+        accountId: string;
+        resolved: unknown;
+      }) =>
+        setDiscordGuildChannelAllowlist(cfg, accountId, mapDiscordSetupAllowlistEntries(resolved)),
+    }),
+    allowFrom: createAccountScopedAllowFromSection({
+      channel,
+      credentialInputKey: "token",
+      helpTitle: "Discord allowlist",
+      helpLines: [
+        t("wizard.discord.allowlistIntro"),
+        t("wizard.discord.examples"),
+        "- 123456789012345678",
+        "- @alice",
+        "- alice#1234",
+        t("wizard.discord.multipleEntries"),
+        t("wizard.channels.docs", { link: formatDocsLink("/discord", "discord") }),
+      ],
+      message: t("wizard.discord.allowFromPrompt"),
+      placeholder: "@alice, 123456789012345678",
+      invalidWithoutCredentialNote: t("wizard.discord.allowFromInvalidWithoutToken"),
+      parseId: parseDiscordAllowFromId,
+      resolveEntries: handlers.resolveAllowFromEntries,
+    }),
+    dmPolicy: discordDmPolicy,
+    disable: (cfg: KlawConfig) => setSetupChannelEnabled(cfg, channel, false),
+  } satisfies ChannelSetupWizard;
+}

package/src/setup-runtime-helpers.ts

@@ -0,0 +1,10 @@
+export {
+  createAccountScopedAllowFromSection,
+  createAccountScopedGroupAccessSection,
+  createLegacyCompatChannelDmPolicy,
+  parseMentionOrPrefixedId,
+  patchChannelConfigForAccount,
+  promptLegacyChannelAllowFromForAccount,
+  resolveEntriesWithOptionalToken,
+  setSetupChannelEnabled,
+} from "klaw/plugin-sdk/setup-runtime";

package/src/setup-surface.test.ts

@@ -0,0 +1,137 @@
+import type { KlawConfig } from "klaw/plugin-sdk/config-contracts";
+import { describe, expect, it } from "vitest";
+import { createDiscordSetupWizardBase } from "./setup-core.js";
+
+const discordSetupWizard = createDiscordSetupWizardBase({
+  promptAllowFrom: async ({ cfg }) => cfg,
+  resolveAllowFromEntries: async ({ entries }) =>
+    entries.map((entry) => ({
+      input: entry,
+      resolved: false,
+      id: null,
+    })),
+  resolveGroupAllowlist: async ({ entries }) =>
+    entries.map((entry) => ({
+      input: entry,
+      resolved: false,
+    })),
+});
+
+describe("discordSetupWizard.dmPolicy", () => {
+  it("reads the named-account DM policy instead of the channel root", () => {
+    expect(
+      discordSetupWizard.dmPolicy?.getCurrent(
+        {
+          channels: {
+            discord: {
+              dmPolicy: "disabled",
+              accounts: {
+                alerts: {
+                  dmPolicy: "allowlist",
+                  token: "discord-token",
+                },
+              },
+            },
+          },
+        } as KlawConfig,
+        "alerts",
+      ),
+    ).toBe("allowlist");
+  });
+
+  it("reports account-scoped config keys for named accounts", () => {
+    expect(discordSetupWizard.dmPolicy?.resolveConfigKeys?.({}, "alerts")).toEqual({
+      policyKey: "channels.discord.accounts.alerts.dmPolicy",
+      allowFromKey: "channels.discord.accounts.alerts.allowFrom",
+    });
+  });
+
+  it('writes open policy state to the named account and preserves inherited allowFrom with "*"', () => {
+    const next = discordSetupWizard.dmPolicy?.setPolicy(
+      {
+        channels: {
+          discord: {
+            allowFrom: ["123"],
+            accounts: {
+              alerts: {
+                token: "discord-token",
+              },
+            },
+          },
+        },
+      } as KlawConfig,
+      "open",
+      "alerts",
+    );
+
+    expect(next?.channels?.discord?.dmPolicy).toBeUndefined();
+    expect(next?.channels?.discord?.accounts?.alerts?.dmPolicy).toBe("open");
+    expect(next?.channels?.discord?.accounts?.alerts?.allowFrom).toEqual(["123", "*"]);
+  });
+});
+
+describe("discordSetupWizard.status", () => {
+  it("uses configured defaultAccount for omitted setup configured state", async () => {
+    const configured = await discordSetupWizard.status.resolveConfigured({
+      cfg: {
+        channels: {
+          discord: {
+            defaultAccount: "work",
+            token: "discord-root-token",
+            accounts: {
+              alerts: {
+                token: "discord-alerts-token",
+              },
+              work: {
+                token: "",
+              },
+            },
+          },
+        },
+      } as KlawConfig,
+    });
+
+    expect(configured).toBe(false);
+  });
+});
+
+describe("discordSetupWizard.groupAccess", () => {
+  it("writes resolved Discord channel rows to their selected guild and channel", () => {
+    const next = discordSetupWizard.groupAccess?.applyAllowlist?.({
+      cfg: {
+        channels: {
+          discord: {
+            guilds: {
+              existing: {
+                channels: {
+                  keep: { enabled: true },
+                },
+              },
+            },
+          },
+        },
+      } as KlawConfig,
+      accountId: "default",
+      resolved: [
+        {
+          input: "Klaw/#triage",
+          resolved: true,
+          guildId: "guild-1",
+          channelId: "channel-1",
+        },
+        {
+          input: "missing",
+          resolved: false,
+        },
+      ],
+    });
+
+    expect(next?.channels?.discord?.guilds?.["guild-1"]?.channels?.["channel-1"]).toEqual({
+      enabled: true,
+    });
+    expect(next?.channels?.discord?.guilds?.["*"]).toBeUndefined();
+    expect(next?.channels?.discord?.guilds?.existing?.channels?.keep).toEqual({
+      enabled: true,
+    });
+  });
+});

package/src/setup-surface.ts

@@ -0,0 +1,132 @@
+import {
+  createSetupTranslator,
+  type ChannelSetupWizard,
+  type KlawConfig,
+  type WizardPrompter,
+} from "klaw/plugin-sdk/setup-runtime";
+import { formatDocsLink } from "klaw/plugin-sdk/setup-tools";
+import { resolveDiscordAccountAllowFrom } from "./accounts.js";
+import { resolveDiscordChannelAllowlist } from "./resolve-channels.js";
+import { resolveDiscordUserAllowlist } from "./resolve-users.js";
+import {
+  resolveDefaultDiscordSetupAccountId,
+  resolveDiscordSetupAccountConfig,
+} from "./setup-account-state.js";
+import { createDiscordSetupWizardBase, parseDiscordAllowFromId } from "./setup-core.js";
+import {
+  promptLegacyChannelAllowFromForAccount,
+  resolveEntriesWithOptionalToken,
+} from "./setup-runtime-helpers.js";
+import { resolveDiscordToken } from "./token.js";
+
+const t = createSetupTranslator();
+
+const channel = "discord" as const;
+
+async function resolveDiscordAllowFromEntries(params: { token?: string; entries: string[] }) {
+  return await resolveEntriesWithOptionalToken({
+    token: params.token,
+    entries: params.entries,
+    buildWithoutToken: (input) => ({
+      input,
+      resolved: false,
+      id: null,
+    }),
+    resolveEntries: async ({ token, entries }) =>
+      (
+        await resolveDiscordUserAllowlist({
+          token,
+          entries,
+        })
+      ).map((entry) => ({
+        input: entry.input,
+        resolved: entry.resolved,
+        id: entry.id ?? null,
+      })),
+  });
+}
+
+async function promptDiscordAllowFrom(params: {
+  cfg: KlawConfig;
+  prompter: WizardPrompter;
+  accountId?: string;
+}): Promise<KlawConfig> {
+  return await promptLegacyChannelAllowFromForAccount({
+    cfg: params.cfg,
+    channel,
+    prompter: params.prompter,
+    accountId: params.accountId,
+    defaultAccountId: resolveDefaultDiscordSetupAccountId(params.cfg),
+    resolveAccount: (cfg, accountId) => resolveDiscordSetupAccountConfig({ cfg, accountId }),
+    noteTitle: t("wizard.discord.allowlistTitle"),
+    noteLines: [
+      t("wizard.discord.allowlistIntro"),
+      t("wizard.discord.examples"),
+      "- 123456789012345678",
+      "- @alice",
+      "- alice#1234",
+      t("wizard.discord.multipleEntries"),
+      t("wizard.channels.docs", { link: formatDocsLink("/discord", "discord") }),
+    ],
+    message: t("wizard.discord.allowFromPrompt"),
+    placeholder: "@alice, 123456789012345678",
+    parseId: parseDiscordAllowFromId,
+    invalidWithoutTokenNote: t("wizard.discord.allowFromInvalidWithoutToken"),
+    resolveExisting: (account, cfg) =>
+      resolveDiscordAccountAllowFrom({ cfg, accountId: account.accountId }) ?? [],
+    resolveToken: (account) =>
+      resolveDiscordToken(params.cfg, { accountId: account.accountId }).token,
+    resolveEntries: async ({ token, entries }) =>
+      (
+        await resolveDiscordUserAllowlist({
+          token,
+          entries,
+        })
+      ).map((entry) => ({
+        input: entry.input,
+        resolved: entry.resolved,
+        id: entry.id ?? null,
+      })),
+  });
+}
+
+async function resolveDiscordGroupAllowlist(params: {
+  cfg: KlawConfig;
+  accountId: string;
+  credentialValues: { token?: string };
+  entries: string[];
+}) {
+  return await resolveEntriesWithOptionalToken({
+    token:
+      resolveDiscordToken(params.cfg, { accountId: params.accountId }).token ||
+      (typeof params.credentialValues.token === "string" ? params.credentialValues.token : ""),
+    entries: params.entries,
+    buildWithoutToken: (input) => ({
+      input,
+      resolved: false,
+    }),
+    resolveEntries: async ({ token, entries }) =>
+      await resolveDiscordChannelAllowlist({
+        token,
+        entries,
+      }),
+  });
+}
+
+export const discordSetupWizard: ChannelSetupWizard = createDiscordSetupWizardBase({
+  promptAllowFrom: promptDiscordAllowFrom,
+  resolveAllowFromEntries: async ({ cfg, accountId, credentialValues, entries }) =>
+    await resolveDiscordAllowFromEntries({
+      token:
+        resolveDiscordToken(cfg, { accountId }).token ||
+        (typeof credentialValues.token === "string" ? credentialValues.token : ""),
+      entries,
+    }),
+  resolveGroupAllowlist: async ({ cfg, accountId, credentialValues, entries }) =>
+    await resolveDiscordGroupAllowlist({
+      cfg,
+      accountId,
+      credentialValues,
+      entries,
+    }),
+});

package/src/shared-interactive.test.ts

@@ -0,0 +1,153 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildDiscordInteractiveComponents,
+  buildDiscordPresentationComponents,
+} from "./shared-interactive.js";
+
+describe("buildDiscordInteractiveComponents", () => {
+  it("maps shared buttons and selects into Discord component blocks", () => {
+    expect(
+      buildDiscordInteractiveComponents({
+        blocks: [
+          {
+            type: "buttons",
+            buttons: [
+              { label: "Approve", value: "approve", style: "success" },
+              { label: "Reject", value: "reject", style: "danger" },
+            ],
+          },
+          {
+            type: "select",
+            placeholder: "Pick one",
+            options: [{ label: "Alpha", value: "alpha" }],
+          },
+        ],
+      }),
+    ).toEqual({
+      blocks: [
+        {
+          type: "actions",
+          buttons: [
+            { label: "Approve", style: "success", callbackData: "approve" },
+            { label: "Reject", style: "danger", callbackData: "reject" },
+          ],
+        },
+        {
+          type: "actions",
+          select: {
+            type: "string",
+            placeholder: "Pick one",
+            options: [{ label: "Alpha", value: "alpha" }],
+          },
+        },
+      ],
+    });
+  });
+
+  it("preserves authored shared text blocks around controls", () => {
+    expect(
+      buildDiscordInteractiveComponents({
+        blocks: [
+          { type: "text", text: "First" },
+          {
+            type: "buttons",
+            buttons: [{ label: "Approve", value: "approve", style: "success" }],
+          },
+          { type: "text", text: "Last" },
+        ],
+      }),
+    ).toEqual({
+      blocks: [
+        { type: "text", text: "First" },
+        {
+          type: "actions",
+          buttons: [{ label: "Approve", style: "success", callbackData: "approve" }],
+        },
+        { type: "text", text: "Last" },
+      ],
+    });
+  });
+
+  it("preserves URL-only buttons as Discord link buttons", () => {
+    expect(
+      buildDiscordInteractiveComponents({
+        blocks: [
+          {
+            type: "buttons",
+            buttons: [{ label: "Docs", url: "https://example.com/docs" }],
+          },
+        ],
+      }),
+    ).toEqual({
+      blocks: [
+        {
+          type: "actions",
+          buttons: [{ label: "Docs", style: "link", url: "https://example.com/docs" }],
+        },
+      ],
+    });
+  });
+
+  it("splits long shared button rows to stay within Discord action limits", () => {
+    expect(
+      buildDiscordInteractiveComponents({
+        blocks: [
+          {
+            type: "buttons",
+            buttons: [
+              { label: "One", value: "1" },
+              { label: "Two", value: "2" },
+              { label: "Three", value: "3" },
+              { label: "Four", value: "4" },
+              { label: "Five", value: "5" },
+              { label: "Six", value: "6" },
+            ],
+          },
+        ],
+      }),
+    ).toEqual({
+      blocks: [
+        {
+          type: "actions",
+          buttons: [
+            { label: "One", style: "secondary", callbackData: "1" },
+            { label: "Two", style: "secondary", callbackData: "2" },
+            { label: "Three", style: "secondary", callbackData: "3" },
+            { label: "Four", style: "secondary", callbackData: "4" },
+            { label: "Five", style: "secondary", callbackData: "5" },
+          ],
+        },
+        {
+          type: "actions",
+          buttons: [{ label: "Six", style: "secondary", callbackData: "6" }],
+        },
+      ],
+    });
+  });
+
+  it("does not duplicate presentation text when appending controls", () => {
+    expect(
+      buildDiscordPresentationComponents({
+        title: "Status",
+        blocks: [
+          { type: "text", text: "Build completed" },
+          { type: "context", text: "main branch" },
+          {
+            type: "buttons",
+            buttons: [{ label: "Open", value: "open" }],
+          },
+        ],
+      }),
+    ).toEqual({
+      blocks: [
+        { type: "text", text: "Status" },
+        { type: "text", text: "Build completed" },
+        { type: "text", text: "-# main branch" },
+        {
+          type: "actions",
+          buttons: [{ label: "Open", style: "secondary", callbackData: "open" }],
+        },
+      ],
+    });
+  });
+});