feat: add zalouser channel + directory CLI (#1032) (thanks @suminhthanh)

- Unified UX: channels login + message send; no plugin-specific top-level command\n- Added generic directory CLI for channel identity/groups\n- Docs: channel + plugin pages

src/channels/plugins/types.adapters.ts

@@ -4,6 +4,7 @@ import type { RuntimeEnv } from "../../runtime.js";
 import type {
   ChannelAccountSnapshot,
   ChannelAccountState,
+  ChannelDirectoryEntry,
   ChannelGroupContext,
   ChannelHeartbeatDeps,
   ChannelLogSink,
@@ -219,6 +220,35 @@ export type ChannelHeartbeatAdapter = {
   };
 };
 
+export type ChannelDirectoryAdapter = {
+  self?: (params: {
+    cfg: ClawdbotConfig;
+    accountId?: string | null;
+    runtime: RuntimeEnv;
+  }) => Promise<ChannelDirectoryEntry | null>;
+  listPeers?: (params: {
+    cfg: ClawdbotConfig;
+    accountId?: string | null;
+    query?: string | null;
+    limit?: number | null;
+    runtime: RuntimeEnv;
+  }) => Promise<ChannelDirectoryEntry[]>;
+  listGroups?: (params: {
+    cfg: ClawdbotConfig;
+    accountId?: string | null;
+    query?: string | null;
+    limit?: number | null;
+    runtime: RuntimeEnv;
+  }) => Promise<ChannelDirectoryEntry[]>;
+  listGroupMembers?: (params: {
+    cfg: ClawdbotConfig;
+    accountId?: string | null;
+    groupId: string;
+    limit?: number | null;
+    runtime: RuntimeEnv;
+  }) => Promise<ChannelDirectoryEntry[]>;
+};
+
 export type ChannelElevatedAdapter = {
   allowFromFallback?: (params: {
     cfg: ClawdbotConfig;

src/channels/plugins/types.core.ts

@@ -216,6 +216,17 @@ export type ChannelMessagingAdapter = {
   normalizeTarget?: (raw: string) => string | undefined;
 };
 
+export type ChannelDirectoryEntryKind = "user" | "group" | "channel";
+
+export type ChannelDirectoryEntry = {
+  kind: ChannelDirectoryEntryKind;
+  id: string;
+  name?: string;
+  handle?: string;
+  avatarUrl?: string;
+  raw?: unknown;
+};
+
 export type ChannelMessageActionName = ChannelMessageActionNameFromList;
 
 export type ChannelMessageActionContext = {

src/channels/plugins/types.plugin.ts

@@ -3,6 +3,7 @@ import type {
   ChannelAuthAdapter,
   ChannelCommandAdapter,
   ChannelConfigAdapter,
+  ChannelDirectoryAdapter,
   ChannelElevatedAdapter,
   ChannelGatewayAdapter,
   ChannelGroupAdapter,
@@ -51,6 +52,7 @@ export type ChannelPlugin<ResolvedAccount = any> = {
   streaming?: ChannelStreamingAdapter;
   threading?: ChannelThreadingAdapter;
   messaging?: ChannelMessagingAdapter;
+  directory?: ChannelDirectoryAdapter;
   actions?: ChannelMessageActionAdapter;
   heartbeat?: ChannelHeartbeatAdapter;
   // Channel-owned agent tools (login flows, etc.).

src/channels/plugins/types.ts

@@ -8,6 +8,7 @@ export type {
   ChannelAuthAdapter,
   ChannelCommandAdapter,
   ChannelConfigAdapter,
+  ChannelDirectoryAdapter,
   ChannelElevatedAdapter,
   ChannelGatewayAdapter,
   ChannelGatewayContext,
@@ -30,6 +31,8 @@ export type {
   ChannelAgentTool,
   ChannelAgentToolFactory,
   ChannelCapabilities,
+  ChannelDirectoryEntry,
+  ChannelDirectoryEntryKind,
   ChannelGroupContext,
   ChannelHeartbeatDeps,
   ChannelId,

src/cli/channels-cli.ts

@@ -156,9 +156,9 @@ export function registerChannelsCli(program: Command) {
 
   channels
     .command("login")
-    .description("Link a channel account (WhatsApp Web only)")
+    .description("Link a channel account (if supported)")
     .option("--channel <channel>", "Channel alias (default: whatsapp)")
-    .option("--account <id>", "WhatsApp account id (accountId)")
+    .option("--account <id>", "Account id (accountId)")
     .option("--verbose", "Verbose connection logs", false)
     .action(async (opts) => {
       try {

src/cli/directory-cli.ts

@@ -0,0 +1,193 @@
+import type { Command } from "commander";
+
+import { resolveChannelDefaultAccountId } from "../channels/plugins/helpers.js";
+import { getChannelPlugin, normalizeChannelId } from "../channels/plugins/index.js";
+import { DEFAULT_CHAT_CHANNEL } from "../channels/registry.js";
+import { loadConfig } from "../config/config.js";
+import { danger } from "../globals.js";
+import { defaultRuntime } from "../runtime.js";
+import { formatDocsLink } from "../terminal/links.js";
+import { theme } from "../terminal/theme.js";
+
+function parseLimit(value: unknown): number | null {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    if (value <= 0) return null;
+    return Math.floor(value);
+  }
+  if (typeof value !== "string") return null;
+  const raw = value.trim();
+  if (!raw) return null;
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) return null;
+  return parsed;
+}
+
+function formatEntry(entry: { kind: string; id: string; name?: string | undefined }): string {
+  const name = entry.name?.trim();
+  return name ? `${entry.id}\t${name}` : entry.id;
+}
+
+export function registerDirectoryCli(program: Command) {
+  const directory = program
+    .command("directory")
+    .description("Directory lookups (self, peers, groups) for channels that support it")
+    .addHelpText(
+      "after",
+      () =>
+        `\n${theme.muted("Docs:")} ${formatDocsLink(
+          "/cli/directory",
+          "docs.clawd.bot/cli/directory",
+        )}\n`,
+    )
+    .action(() => {
+      directory.help({ error: true });
+    });
+
+  const withChannel = (cmd: Command) =>
+    cmd
+      .option("--channel <name>", "Channel (default: whatsapp)")
+      .option("--account <id>", "Account id (accountId)")
+      .option("--json", "Output JSON", false);
+
+  const resolve = (opts: { channel?: string; account?: string }) => {
+    const cfg = loadConfig();
+    const channelInput = opts.channel ?? DEFAULT_CHAT_CHANNEL;
+    const channelId = normalizeChannelId(channelInput);
+    if (!channelId) {
+      throw new Error(`Unsupported channel: ${channelInput}`);
+    }
+    const plugin = getChannelPlugin(channelId);
+    if (!plugin?.directory) {
+      throw new Error(`Channel ${channelId} does not support directory`);
+    }
+    const accountId = opts.account?.trim() || resolveChannelDefaultAccountId({ plugin, cfg });
+    return { cfg, channelId, accountId, plugin };
+  };
+
+  withChannel(directory.command("self").description("Show the current account user")).action(
+    async (opts) => {
+      try {
+        const { cfg, channelId, accountId, plugin } = resolve({
+          channel: opts.channel as string | undefined,
+          account: opts.account as string | undefined,
+        });
+        const fn = plugin.directory?.self;
+        if (!fn) throw new Error(`Channel ${channelId} does not support directory self`);
+        const result = await fn({ cfg, accountId, runtime: defaultRuntime });
+        if (opts.json) {
+          defaultRuntime.log(JSON.stringify(result, null, 2));
+          return;
+        }
+        if (!result) {
+          defaultRuntime.log("not available");
+          return;
+        }
+        defaultRuntime.log(formatEntry(result));
+      } catch (err) {
+        defaultRuntime.error(danger(String(err)));
+        defaultRuntime.exit(1);
+      }
+    },
+  );
+
+  const peers = directory.command("peers").description("Peer directory (contacts/users)");
+  withChannel(peers.command("list").description("List peers"))
+    .option("--query <text>", "Optional search query")
+    .option("--limit <n>", "Limit results")
+    .action(async (opts) => {
+      try {
+        const { cfg, channelId, accountId, plugin } = resolve({
+          channel: opts.channel as string | undefined,
+          account: opts.account as string | undefined,
+        });
+        const fn = plugin.directory?.listPeers;
+        if (!fn) throw new Error(`Channel ${channelId} does not support directory peers`);
+        const result = await fn({
+          cfg,
+          accountId,
+          query: (opts.query as string | undefined) ?? null,
+          limit: parseLimit(opts.limit),
+          runtime: defaultRuntime,
+        });
+        if (opts.json) {
+          defaultRuntime.log(JSON.stringify(result, null, 2));
+          return;
+        }
+        for (const entry of result) {
+          defaultRuntime.log(formatEntry(entry));
+        }
+      } catch (err) {
+        defaultRuntime.error(danger(String(err)));
+        defaultRuntime.exit(1);
+      }
+    });
+
+  const groups = directory.command("groups").description("Group directory");
+  withChannel(groups.command("list").description("List groups"))
+    .option("--query <text>", "Optional search query")
+    .option("--limit <n>", "Limit results")
+    .action(async (opts) => {
+      try {
+        const { cfg, channelId, accountId, plugin } = resolve({
+          channel: opts.channel as string | undefined,
+          account: opts.account as string | undefined,
+        });
+        const fn = plugin.directory?.listGroups;
+        if (!fn) throw new Error(`Channel ${channelId} does not support directory groups`);
+        const result = await fn({
+          cfg,
+          accountId,
+          query: (opts.query as string | undefined) ?? null,
+          limit: parseLimit(opts.limit),
+          runtime: defaultRuntime,
+        });
+        if (opts.json) {
+          defaultRuntime.log(JSON.stringify(result, null, 2));
+          return;
+        }
+        for (const entry of result) {
+          defaultRuntime.log(formatEntry(entry));
+        }
+      } catch (err) {
+        defaultRuntime.error(danger(String(err)));
+        defaultRuntime.exit(1);
+      }
+    });
+
+  withChannel(
+    groups
+      .command("members")
+      .description("List group members")
+      .requiredOption("--group-id <id>", "Group id"),
+  )
+    .option("--limit <n>", "Limit results")
+    .action(async (opts) => {
+      try {
+        const { cfg, channelId, accountId, plugin } = resolve({
+          channel: opts.channel as string | undefined,
+          account: opts.account as string | undefined,
+        });
+        const fn = plugin.directory?.listGroupMembers;
+        if (!fn) throw new Error(`Channel ${channelId} does not support group members listing`);
+        const groupId = String(opts.groupId ?? "").trim();
+        if (!groupId) throw new Error("Missing --group-id");
+        const result = await fn({
+          cfg,
+          accountId,
+          groupId,
+          limit: parseLimit(opts.limit),
+          runtime: defaultRuntime,
+        });
+        if (opts.json) {
+          defaultRuntime.log(JSON.stringify(result, null, 2));
+          return;
+        }
+        for (const entry of result) {
+          defaultRuntime.log(formatEntry(entry));
+        }
+      } catch (err) {
+        defaultRuntime.error(danger(String(err)));
+        defaultRuntime.exit(1);
+      }
+    });
+}

src/cli/program/register.subclis.ts

@@ -5,6 +5,7 @@ import { registerChannelsCli } from "../channels-cli.js";
 import { registerCronCli } from "../cron-cli.js";
 import { registerDaemonCli } from "../daemon-cli.js";
 import { registerDnsCli } from "../dns-cli.js";
+import { registerDirectoryCli } from "../directory-cli.js";
 import { registerDocsCli } from "../docs-cli.js";
 import { registerGatewayCli } from "../gateway-cli.js";
 import { registerHooksCli } from "../hooks-cli.js";
@@ -36,6 +37,7 @@ export function registerSubCliCommands(program: Command) {
   registerPairingCli(program);
   registerPluginsCli(program);
   registerChannelsCli(program);
+  registerDirectoryCli(program);
   registerSecurityCli(program);
   registerSkillsCli(program);
   registerUpdateCli(program);