// Channel setup status helpers format channel setup progress and docs links.

import { formatDocsLink } from "../../packages/terminal-core/src/links.js";

import { sanitizeTerminalText } from "../../packages/terminal-core/src/safe-text.js";

import { resolveAgentWorkspaceDir, resolveDefaultAgentId } from "../agents/agent-scope.js";

import { listChatChannels } from "../channels/chat-meta.js";

import type { ChannelPluginCatalogEntry } from "../channels/plugins/catalog.js";

import { listChannelSetupPlugins } from "../channels/plugins/setup-registry.js";

import type {

ChannelSetupPlugin,

ChannelSetupStatus,

ChannelSetupWizardAdapter,

SetupChannelsOptions,

} from "../channels/plugins/setup-wizard-types.js";

import type { ChannelMeta } from "../channels/plugins/types.core.js";

import { formatChannelPrimerLine, formatChannelSelectionLine } from "../channels/registry.js";

import { formatCliCommand } from "../cli/command-format.js";

import { resolveChannelSetupEntries } from "../commands/channel-setup/discovery.js";

import { shouldShowChannelInSetup } from "../commands/channel-setup/discovery.js";

import { resolveChannelSetupWizardAdapterForPlugin } from "../commands/channel-setup/registry.js";

import type { ChannelChoice } from "../commands/onboard-types.js";

import { isChannelConfigured } from "../config/channel-configured.js";

import type { OpenClawConfig } from "../config/types.openclaw.js";

import {

findBundledPluginSourceInMap,

resolveBundledPluginSources,

type BundledPluginSource,

} from "../plugins/bundled-sources.js";

import { t, wizardT } from "../wizard/i18n/index.js";

import type { WizardPrompter } from "../wizard/prompts.js";

import type { FlowContribution } from "./types.js";

type ChannelStatusSummary = {

installedPlugins: ChannelSetupPlugin[];

catalogEntries: ChannelPluginCatalogEntry[];

installedCatalogEntries: ChannelPluginCatalogEntry[];

statusByChannel: Map<ChannelChoice, ChannelSetupStatus>;

statusLines: string[];

};

type ChannelSetupSelectionContribution = FlowContribution & {

kind: "channel";

surface: "setup";

channel: ChannelChoice;

source: "catalog" | "core" | "plugin";

};

type ChannelSetupSelectionEntry = {

id: ChannelChoice;

meta: {

id: string;

label: string;

selectionLabel?: string;

exposure?: { setup?: boolean };

showConfigured?: boolean;

showInSetup?: boolean;

};

};

const CHANNEL_PRIMER_BLURB_KEYS: Record<string, string> = {

clickclack: "wizard.channelsPrimer.blurbs.clickclack",

discord: "wizard.channelsPrimer.blurbs.discord",

feishu: "wizard.channelsPrimer.blurbs.feishu",

googlechat: "wizard.channelsPrimer.blurbs.googlechat",

imessage: "wizard.channelsPrimer.blurbs.imessage",

irc: "wizard.channelsPrimer.blurbs.irc",

line: "wizard.channelsPrimer.blurbs.line",

mattermost: "wizard.channelsPrimer.blurbs.mattermost",

matrix: "wizard.channelsPrimer.blurbs.matrix",

msteams: "wizard.channelsPrimer.blurbs.msteams",

"nextcloud-talk": "wizard.channelsPrimer.blurbs.nextcloudTalk",

nostr: "wizard.channelsPrimer.blurbs.nostr",

qqbot: "wizard.channelsPrimer.blurbs.qqbot",

signal: "wizard.channelsPrimer.blurbs.signal",

slack: "wizard.channelsPrimer.blurbs.slack",

"synology-chat": "wizard.channelsPrimer.blurbs.synologyChat",

telegram: "wizard.channelsPrimer.blurbs.telegram",

tlon: "wizard.channelsPrimer.blurbs.tlon",

twitch: "wizard.channelsPrimer.blurbs.twitch",

wecom: "wizard.channelsPrimer.blurbs.wecom",

whatsapp: "wizard.channelsPrimer.blurbs.whatsapp",

yuanbao: "wizard.channelsPrimer.blurbs.yuanbao",

zalo: "wizard.channelsPrimer.blurbs.zalo",

zalouser: "wizard.channelsPrimer.blurbs.zalouser",

};

function buildChannelSetupSelectionContribution(params: {

channel: ChannelChoice;

label: string;

hint?: string;

source: "catalog" | "core" | "plugin";

}): ChannelSetupSelectionContribution {

return {

id: `channel:setup:${params.channel}`,

kind: "channel",

surface: "setup",

channel: params.channel,

option: {

value: params.channel,

label: params.label,

...(params.hint ? { hint: params.hint } : {}),

},

source: params.source,

};

}

function formatSetupSelectionLabel(label: string, fallback: string): string {

return (

sanitizeTerminalText(label).trim() ||

sanitizeTerminalText(fallback).trim() ||

"<invalid channel>"

);

}

function formatSetupSelectionHint(hint: string | undefined): string | undefined {

if (!hint) {

return undefined;

}

return sanitizeTerminalText(hint) || undefined;

}

function formatSetupDisplayText(value: string | undefined, fallback = ""): string {

return (

sanitizeTerminalText(value ?? "").trim() ||

sanitizeTerminalText(fallback).trim() ||

"<invalid channel>"

);

}

function formatSetupFreeText(value: string | undefined): string {

return sanitizeTerminalText(value ?? "").trim();

}

function formatSetupOptionalDisplayText(value: string | undefined): string | undefined {

const safe = sanitizeTerminalText(value ?? "").trim();

return safe || undefined;

}

function formatSetupDisplayList(values: readonly string[] | undefined): string[] | undefined {

const safe = (values ?? []).flatMap((value) => {

const sanitized = formatSetupOptionalDisplayText(value);

return sanitized ? [sanitized] : [];

});

return safe.length > 0 ? safe : undefined;

}

function formatSetupDisplayMeta(meta: ChannelMeta): ChannelMeta {

const safeId = formatSetupDisplayText(meta.id, "<invalid channel>");

const safeLabel = formatSetupDisplayText(meta.label, safeId);

const safeSelectionDocsPrefix = formatSetupOptionalDisplayText(meta.selectionDocsPrefix);

const safeSelectionExtras = formatSetupDisplayList(meta.selectionExtras);

return {

...meta,

id: safeId,

label: safeLabel,

selectionLabel: formatSetupDisplayText(meta.selectionLabel, safeLabel),

docsPath: formatSetupDisplayText(meta.docsPath, "/"),

...(meta.docsLabel ? { docsLabel: formatSetupDisplayText(meta.docsLabel, safeId) } : {}),

blurb: formatSetupFreeText(meta.blurb),

...(safeSelectionDocsPrefix ? { selectionDocsPrefix: safeSelectionDocsPrefix } : {}),

...(safeSelectionExtras ? { selectionExtras: safeSelectionExtras } : {}),

};

}

function formatChannelPrimerBlurb(channel: { id: string; blurb: string }): string {

const key = CHANNEL_PRIMER_BLURB_KEYS[channel.id];

if (!key) {

return channel.blurb;

}

const englishBlurb = wizardT(key, undefined, { locale: "en" });

return channel.blurb === englishBlurb ? t(key) : channel.blurb;

}

function formatChannelSelectionMeta(meta: ChannelMeta): ChannelMeta {

return formatSetupDisplayMeta({

...meta,

blurb: formatChannelPrimerBlurb(meta),

selectionDocsPrefix: meta.selectionDocsPrefix ?? t("common.docs"),

});

}

function localizeChannelStatusLabel(label: string): string {

switch (label) {

case "configured":

return t("wizard.channels.statusConfigured");

case "not configured":

return t("wizard.channels.statusNotConfigured");

case "configured (plugin disabled)":

return t("wizard.channels.statusConfiguredPluginDisabled");

case "installed":

return t("wizard.channels.statusInstalled");

case "installed (plugin disabled)":

return t("wizard.channels.statusInstalledPluginDisabled");

case "bundled · enable to use":

return t("wizard.channels.statusBundledEnable");

case "install plugin to enable":

return t("wizard.channels.statusInstallPluginEnable");

case "needs app credentials":

return t("wizard.channels.statusNeedsAppCredentials");

case "needs app creds":

return t("wizard.channels.statusNeedsAppCreds");

case "needs auth":

return t("wizard.channels.statusNeedsAuth");

case "needs host + nick":

return t("wizard.channels.statusNeedsHostNick");

case "needs private key":

return t("wizard.channels.statusNeedsPrivateKey");

case "needs QR login":

return t("wizard.channels.statusNeedsQrLogin");

case "needs service account":

return t("wizard.channels.statusNeedsServiceAccount");

case "needs setup":

return t("wizard.channels.statusNeedsSetup");

case "needs token":

return t("wizard.channels.statusNeedsToken");

case "needs tokens":

return t("wizard.channels.statusNeedsTokens");

case "needs token + incoming webhook":

return t("wizard.channels.statusNeedsTokenIncomingWebhook");

case "needs token + secret":

return t("wizard.channels.statusNeedsTokenSecret");

case "needs token + url":

return t("wizard.channels.statusNeedsTokenUrl");

case "needs username, token, and clientId":

return t("wizard.channels.statusNeedsUsernameTokenClientId");

case "linked":

return t("wizard.channels.statusLinked");

case "logged in":

return t("wizard.channels.statusLoggedIn");

case "not linked":

return t("wizard.channels.statusNotLinked");

case "recommended · configured":

return t("wizard.channels.statusRecommendedConfigured");

case "recommended · logged in":

return t("wizard.channels.statusRecommendedLoggedIn");

case "recommended · newcomer-friendly":

return t("wizard.channels.statusRecommendedNewcomerFriendly");

case "recommended · QR login":

return t("wizard.channels.statusRecommendedQrLogin");

case "self-hosted chat":

return t("wizard.channels.statusSelfHostedChat");

case "signal-cli found":

return t("wizard.channels.statusSignalCliFound");

case "signal-cli missing":

return t("wizard.channels.statusSignalCliMissing");

case "urbit messenger":

return t("wizard.channels.statusUrbitMessenger");

case "configured (connection not verified)":

return t("wizard.channels.statusConfiguredConnectionNotVerified");

default:

break;

}

const connectedAsPrefix = "connected as ";

if (label.startsWith(connectedAsPrefix)) {

return t("wizard.channels.statusConnectedAs", { name: label.slice(connectedAsPrefix.length) });

}

return label;

}

function localizeChannelStatusLine(line: string): string {

const separator = ": ";

const index = line.lastIndexOf(separator);

if (index < 0) {

return localizeChannelStatusLabel(line);

}

return `${line.slice(0, index + separator.length)}${localizeChannelStatusLabel(

line.slice(index + separator.length),

)}`;

}

function localizeChannelSetupStatus<T extends { selectionHint?: string; statusLines: string[] }>(

status: T,

): T {

return {

...status,

statusLines: status.statusLines.map(localizeChannelStatusLine),

...(status.selectionHint

? { selectionHint: localizeChannelStatusLabel(status.selectionHint) }

: {}),

};

}

/**

* Hint shown next to an installable channel option in the selection menu when

* we don't yet have a runtime-collected status. Mirrors the "configured" /

* "installed" affordance other channels get so users can see "download from

* <npm-spec>" before committing to install.

*

* Bundled channels (the plugin lives under `extensions/<id>` in the host

* repo, e.g. Signal / Tlon / Twitch / Slack) are NOT downloaded from npm —

* they ship with the host. Even when their `package.json` declares an

* `npmSpec` (or the catalog falls back to the package name), surfacing

* "download from <npm-spec>" misleads users into believing the plugin is

* missing. For bundled channels we suppress the npm hint entirely so the

* menu shows the same neutral "plugin · install" affordance used when no

* npm source is known.

*/

export function resolveCatalogChannelSelectionHint(

entry: { install?: { npmSpec?: string } },

options?: { bundledLocalPath?: string | null },

): string {

const npmSpec = entry.install?.npmSpec?.trim();

if (npmSpec && !options?.bundledLocalPath) {

return `download from ${formatSetupSelectionLabel(npmSpec, npmSpec)}`;

}

return "";

}

/**

* Look up the bundled-source entry for a catalog channel, regardless of

* whether the catalog refers to it by `pluginId` or `npmSpec`. We use this

* to detect bundled channels in the selection menu so we can suppress the

* misleading "download from <npm-spec>" hint for plugins that already ship

* with the host (Signal / Tlon / Twitch / Slack ...).

*/

export function findBundledSourceForCatalogChannel(params: {

bundled: ReadonlyMap<string, BundledPluginSource>;

entry: { id: string; pluginId?: string; install?: { npmSpec?: string } };

}): BundledPluginSource | undefined {

const pluginId = params.entry.pluginId?.trim() || params.entry.id.trim();

if (pluginId) {

const byId = findBundledPluginSourceInMap({

bundled: params.bundled,

lookup: { kind: "pluginId", value: pluginId },

});

if (byId) {

return byId;

}

}

const npmSpec = params.entry.install?.npmSpec?.trim();

if (npmSpec) {

return findBundledPluginSourceInMap({

bundled: params.bundled,

lookup: { kind: "npmSpec", value: npmSpec },

});

}

return undefined;

}

export async function collectChannelStatus(params: {

cfg: OpenClawConfig;

options?: SetupChannelsOptions;

accountOverrides: Partial<Record<ChannelChoice, string>>;

installedPlugins?: ChannelSetupPlugin[];

resolveAdapter?: (channel: ChannelChoice) => ChannelSetupWizardAdapter | undefined;

}): Promise<ChannelStatusSummary> {

const installedPlugins = params.installedPlugins ?? listChannelSetupPlugins();

const workspaceDir = resolveAgentWorkspaceDir(params.cfg, resolveDefaultAgentId(params.cfg));

const { installedCatalogEntries, installableCatalogEntries } = resolveChannelSetupEntries({

cfg: params.cfg,

installedPlugins,

workspaceDir,

});

const bundledSources = resolveBundledPluginSources({ workspaceDir });

const resolveAdapter =

params.resolveAdapter ??

((channel: ChannelChoice) =>

resolveChannelSetupWizardAdapterForPlugin(

installedPlugins.find((plugin) => plugin.id === channel),

));

const statusEntries = await Promise.all(

installedPlugins.flatMap((plugin) => {

if (!shouldShowChannelInSetup(plugin.meta)) {

return [];

}

const adapter = resolveAdapter(plugin.id);

if (!adapter) {

return [];

}

return adapter.getStatus({

cfg: params.cfg,

options: params.options,

accountOverrides: params.accountOverrides,

});

}),

);

const statusByChannel = new Map(

statusEntries.map((entry: ChannelSetupStatus) => [entry.channel, entry]),

);

const fallbackStatuses = listChatChannels()

.filter((meta) => shouldShowChannelInSetup(meta))

.filter((meta) => !statusByChannel.has(meta.id))

.map((meta) => {

const configured = isChannelConfigured(params.cfg, meta.id);

const statusLabel = configured ? "configured (plugin disabled)" : "not configured";

return {

channel: meta.id,

configured,

statusLines: [`${formatSetupSelectionLabel(meta.label, meta.id)}: ${statusLabel}`],

selectionHint: configured ? "configured · plugin disabled" : "not configured",

quickstartScore: 0,

};

});

const discoveredPluginStatuses = installedCatalogEntries

.filter((entry) => !statusByChannel.has(entry.id as ChannelChoice))

.map((entry) => {

const configured = isChannelConfigured(params.cfg, entry.id);

const pluginEnabled =

params.cfg.plugins?.entries?.[entry.pluginId ?? entry.id]?.enabled !== false;

const statusLabel = configured

? pluginEnabled

? "configured"

: "configured (plugin disabled)"

: pluginEnabled

? "installed"

: "installed (plugin disabled)";

return {

channel: entry.id as ChannelChoice,

configured,

statusLines: [`${formatSetupSelectionLabel(entry.meta.label, entry.id)}: ${statusLabel}`],

selectionHint: statusLabel,

quickstartScore: 0,

};

});

const catalogStatuses = installableCatalogEntries.map((entry) => {

const bundledLocalPath =

findBundledSourceForCatalogChannel({ bundled: bundledSources, entry })?.localPath ?? null;

const isBundled = Boolean(bundledLocalPath);

// For bundled channels we already have the plugin code on disk; the user

// just needs to enable + configure it. Reflect that in the status line so

// it does not read like a fresh "install plugin to enable" download flow.

const statusLabel = isBundled ? "bundled · enable to use" : "install plugin to enable";

return {

channel: entry.id,

configured: false,

statusLines: [`${formatSetupSelectionLabel(entry.meta.label, entry.id)}: ${statusLabel}`],

selectionHint: resolveCatalogChannelSelectionHint(entry, { bundledLocalPath }),

quickstartScore: 0,

};

});

const combinedStatuses = [

...statusEntries,

...fallbackStatuses,

...discoveredPluginStatuses,

...catalogStatuses,

].map(localizeChannelSetupStatus);

const mergedStatusByChannel = new Map(combinedStatuses.map((entry) => [entry.channel, entry]));

const statusLines = combinedStatuses.flatMap((entry) => entry.statusLines);

return {

installedPlugins,

catalogEntries: installableCatalogEntries,

installedCatalogEntries,

statusByChannel: mergedStatusByChannel,

statusLines,

};

}

export async function noteChannelStatus(params: {

cfg: OpenClawConfig;

prompter: WizardPrompter;

options?: SetupChannelsOptions;

accountOverrides?: Partial<Record<ChannelChoice, string>>;

installedPlugins?: ChannelSetupPlugin[];

resolveAdapter?: (channel: ChannelChoice) => ChannelSetupWizardAdapter | undefined;

}): Promise<void> {

const { statusLines } = await collectChannelStatus({

cfg: params.cfg,

options: params.options,

accountOverrides: params.accountOverrides ?? {},

installedPlugins: params.installedPlugins,

resolveAdapter: params.resolveAdapter,

});

if (statusLines.length > 0) {

await params.prompter.note(statusLines.join("\n"), t("wizard.channels.statusTitle"));

}

}

export async function noteChannelPrimer(

prompter: WizardPrompter,

channels: Array<{ id: ChannelChoice; blurb: string; label: string }>,

): Promise<void> {

const channelLines = channels.map((channel) =>

formatChannelPrimerLine(

formatSetupDisplayMeta({

id: channel.id,

label: channel.label,

selectionLabel: channel.label,

docsPath: "/",

blurb: formatChannelPrimerBlurb(channel),

}),

),

);

await prompter.note(

[

t("wizard.channelsPrimer.inboundSafety"),

t("wizard.channelsPrimer.approveWith", {

command: formatCliCommand("openclaw pairing approve <channel> <code>"),

}),

t("wizard.channelsPrimer.openDm"),

t("wizard.channelsPrimer.multiUserDm", {

command: formatCliCommand('openclaw config set session.dmScope "per-channel-peer"'),

}),

t("wizard.channelsPrimer.docs", {

link: formatDocsLink("/channels/pairing", "channels/pairing"),

}),

"",

...channelLines,

].join("\n"),

t("wizard.channelsPrimer.title"),

);

}

export function resolveQuickstartDefault(

statusByChannel: Map<ChannelChoice, { quickstartScore?: number }>,

): ChannelChoice | undefined {

let best: { channel: ChannelChoice; score: number } | null = null;

for (const [channel, status] of statusByChannel) {

if (status.quickstartScore == null) {

continue;

}

if (!best || status.quickstartScore > best.score) {

best = { channel, score: status.quickstartScore };

}

}

return best?.channel;

}

export function resolveChannelSelectionNoteLines(params: {

cfg: OpenClawConfig;

installedPlugins: ChannelSetupPlugin[];

selection: ChannelChoice[];

}): string[] {

const { entries } = resolveChannelSetupEntries({

cfg: params.cfg,

installedPlugins: params.installedPlugins,

workspaceDir: resolveAgentWorkspaceDir(params.cfg, resolveDefaultAgentId(params.cfg)),

});

const selectionNotes = new Map<string, string>();

for (const entry of entries) {

selectionNotes.set(

entry.id,

formatChannelSelectionLine(formatChannelSelectionMeta(entry.meta), formatDocsLink),

);

}

return params.selection

.map((channel) => selectionNotes.get(channel))

.filter((line): line is string => Boolean(line));

}

export function resolveChannelSetupSelectionContributions(params: {

entries: ChannelSetupSelectionEntry[];

statusByChannel: Map<ChannelChoice, { selectionHint?: string }>;

resolveDisabledHint: (channel: ChannelChoice) => string | undefined;

}): ChannelSetupSelectionContribution[] {

const bundledChannelIds = new Set(listChatChannels().map((channel) => channel.id));

return params.entries

.filter((entry) => shouldShowChannelInSetup(entry.meta))

.toSorted((left, right) => compareChannelSetupSelectionEntries(left, right))

.map((entry) => {

const disabledHint = params.resolveDisabledHint(entry.id);

const statusHint = params.statusByChannel.get(entry.id)?.selectionHint;

const hint = [statusHint, disabledHint].filter(Boolean).join(" · ") || undefined;

return buildChannelSetupSelectionContribution({

channel: entry.id,

label: formatSetupSelectionLabel(entry.meta.selectionLabel ?? entry.meta.label, entry.id),

hint: formatSetupSelectionHint(hint),

source: bundledChannelIds.has(entry.id) ? "core" : "plugin",

});

});

}

function compareChannelSetupSelectionEntries(

left: ChannelSetupSelectionEntry,

right: ChannelSetupSelectionEntry,

): number {

const leftLabel = left.meta.selectionLabel ?? left.meta.label;

const rightLabel = right.meta.selectionLabel ?? right.meta.label;

return (

leftLabel.localeCompare(rightLabel, undefined, { numeric: true, sensitivity: "base" }) ||

left.id.localeCompare(right.id, undefined, { numeric: true, sensitivity: "base" })

);

}