dw-kit 1.7.0-rc.2 → 1.8.0-rc.2

package/src/commands/connector.mjs

@@ -0,0 +1,570 @@
+// connector.mjs — `dw connector telegram start|check` CLI.
+//
+// Phase 2 of G-rgoal-realtime-orch: chat connector. Telegram first because
+// the Bot API is the simplest of the candidates (zero OAuth, no native client,
+// long-poll over HTTPS only). Zalo / Slack land next; they share connector.mjs
+// formatters + parser + session-store access.
+//
+// Per docs/dw_remote_agent_first_context_strategy.md §3.1 (clisbot pattern)
+// and §9 (Zalo / chat channel strategy — security requirements applied here).
+
+import { readFileSync, existsSync, mkdirSync, writeFileSync, appendFileSync, chmodSync } from 'node:fs';
+import { join } from 'node:path';
+import yaml from 'js-yaml';
+import chalk from 'chalk';
+import enquirer from 'enquirer';
+const { prompt } = enquirer;
+import { createTelegramClient, isValidTelegramToken, tokenSafeId } from '../lib/telegram-bot.mjs';
+import {
+  normalizeIncoming,
+  parseCommand,
+  splitFirstToken,
+  formatStatus,
+  formatSessionsList,
+  formatSessionShow,
+  formatLogs,
+  formatHelp,
+  formatError,
+  formatUnauthorized,
+  formatStarted,
+} from '../lib/connector.mjs';
+import {
+  createSession,
+  listSessions,
+  getSession,
+  readEvents,
+  readOutput,
+  updateSessionStatus,
+  appendEvent,
+  reconcileStaleSessions,
+  pruneSessions,
+  isValidSessionId,
+  openOutputFd,
+  closeFd,
+  GOAL_MAX_LEN,
+} from '../lib/session-store.mjs';
+import { spawn } from 'node:child_process';
+import { resolve as resolvePath } from 'node:path';
+import { resolveCommandPath, spawnAgent } from '../lib/spawn-helpers.mjs';
+
+const CONNECTORS_CONFIG_PATH = '.dw/config/connectors.yml';
+const CONNECTORS_LOCAL_PATH = '.dw/config/connectors.local.yml'; // gitignored; secrets live here
+const AGENTS_CONFIG_PATH = '.dw/config/agents.yml';
+const STATE_DIR = '.dw/cache/connectors/telegram';
+
+/** Deep-merge with local taking precedence. Arrays are REPLACED, not concat'd. */
+function deepMerge(base, overlay) {
+  if (overlay === undefined || overlay === null) return base;
+  if (typeof base !== 'object' || typeof overlay !== 'object' || Array.isArray(base) || Array.isArray(overlay)) {
+    return overlay;
+  }
+  const out = { ...base };
+  for (const k of Object.keys(overlay)) {
+    out[k] = (k in base) ? deepMerge(base[k], overlay[k]) : overlay[k];
+  }
+  return out;
+}
+
+function loadConnectorsConfig(rootDir = process.cwd()) {
+  const base = join(rootDir, CONNECTORS_CONFIG_PATH);
+  const local = join(rootDir, CONNECTORS_LOCAL_PATH);
+  const hasBase = existsSync(base);
+  const hasLocal = existsSync(local);
+  if (!hasBase && !hasLocal) {
+    throw new Error(
+      `No connectors config found.\n` +
+      `Run: dw connector telegram setup\n` +
+      `(or copy ${CONNECTORS_CONFIG_PATH} from the dw-kit source.)`
+    );
+  }
+  let doc = hasBase ? (yaml.load(readFileSync(base, 'utf8')) || {}) : {};
+  if (hasLocal) {
+    const localDoc = yaml.load(readFileSync(local, 'utf8')) || {};
+    doc = deepMerge(doc, localDoc);
+  }
+  return doc;
+}
+
+function writeLocalConfig(rootDir, patch) {
+  const local = join(rootDir, CONNECTORS_LOCAL_PATH);
+  const dir = join(rootDir, '.dw', 'config');
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const existing = existsSync(local) ? (yaml.load(readFileSync(local, 'utf8')) || {}) : {};
+  const merged = deepMerge(existing, patch);
+  // Add a header comment so end-users understand the file's purpose.
+  const header = [
+    '# .dw/config/connectors.local.yml — GITIGNORED. Secrets live here.',
+    '# Created/updated by `dw connector telegram setup`.',
+    '# Token + allow-list overrides the template in .dw/config/connectors.yml.',
+    '',
+  ].join('\n');
+  writeFileSync(local, header + yaml.dump(merged), 'utf8');
+  // Owner-only perms on POSIX; no-op on Win32.
+  if (process.platform !== 'win32') {
+    try { chmodSync(local, 0o600); } catch { /* harmless */ }
+  }
+  return local;
+}
+
+// Defense-in-depth: deep-clone and replace any secret-shaped fields with
+// `<REDACTED>`. Use this BEFORE printing/serializing any config blob. Even
+// the wizard's pretty-print should go through this if it ever shows the full
+// shape — leak-prevention belt-and-suspenders for F-12.
+//
+// Field-name match list is intentionally broad: bot_token, api_key, token,
+// secret, password, credentials, authorization. Sub-objects recursed; arrays
+// scanned. Token-shaped string values (e.g. Telegram tokens that escape into
+// other fields) also get a value-shape redaction pass.
+const SECRET_FIELD_PATTERN = /\b(bot_token|api_key|api_secret|token|secret|password|credentials?|authorization|private_key|access_key)\b/i;
+const TELEGRAM_TOKEN_VALUE_PATTERN = /\d{6,}:[A-Za-z0-9_-]{30,}/g;
+
+export function redactConfig(obj) {
+  if (obj === null || obj === undefined) return obj;
+  if (typeof obj === 'string') {
+    // Even at string-level, scrub anything that looks like a Telegram token.
+    return obj.replace(TELEGRAM_TOKEN_VALUE_PATTERN, '<REDACTED>');
+  }
+  if (Array.isArray(obj)) return obj.map(redactConfig);
+  if (typeof obj !== 'object') return obj;
+  const out = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (SECRET_FIELD_PATTERN.test(k)) {
+      out[k] = (v === '' || v === null || v === undefined) ? v : '<REDACTED>';
+    } else {
+      out[k] = redactConfig(v);
+    }
+  }
+  return out;
+}
+
+// Exported for tests + reuse.
+export { loadConnectorsConfig, writeLocalConfig, deepMerge, CONNECTORS_LOCAL_PATH };
+
+function loadAgentsConfig(rootDir) {
+  const p = join(rootDir, AGENTS_CONFIG_PATH);
+  if (!existsSync(p)) return { agents: {} };
+  return yaml.load(readFileSync(p, 'utf8')) || { agents: {} };
+}
+
+function loadOffset(rootDir) {
+  const p = join(rootDir, STATE_DIR, 'offset.json');
+  if (!existsSync(p)) return 0;
+  try { return JSON.parse(readFileSync(p, 'utf8')).offset || 0; }
+  catch { return 0; }
+}
+
+function saveOffset(rootDir, offset) {
+  const dir = join(rootDir, STATE_DIR);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, 'offset.json'), JSON.stringify({ offset, ts: new Date().toISOString() }) + '\n', 'utf8');
+}
+
+// ─ Authorization ─
+
+function isAuthorized(cfg, userId) {
+  const allowed = cfg?.telegram?.allowed_user_ids || [];
+  return allowed.map(String).includes(String(userId));
+}
+
+// ─ Audit ─
+
+function auditLog(rootDir, entry) {
+  const p = join(rootDir, '.dw', 'events-global.jsonl');
+  const dir = join(rootDir, '.dw');
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const line = JSON.stringify({ ts: new Date().toISOString(), source: 'connector:telegram', ...entry }) + '\n';
+  try { appendFileSync(p, line, 'utf8'); } catch { /* swallow — audit best-effort */ }
+}
+
+// ─ Command dispatch ─
+
+const HELP_COMMANDS = [
+  { name: 'status', description: 'Show DW status snapshot' },
+  { name: 'sessions [running|all]', description: 'List active/recent sessions' },
+  { name: 'show <id>', description: 'Show one session (state + last output)' },
+  { name: 'logs <id> [tail]', description: 'Tail recent output (default 20 lines)' },
+  { name: 'start <agent> <goal>', description: 'Start a new agent session' },
+  { name: 'stop <id>', description: 'Stop a running session' },
+  { name: 'prune [days]', description: 'Remove old terminal sessions (default 7d)' },
+  { name: 'help', description: 'Show this help' },
+];
+
+function resolveSessionByShortId(short, rootDir) {
+  // Empty short would match every session via endsWith('') — explicit guard
+  // (F-11 from G-dogfood-v1.7 telegram smoke session 2026-05-24).
+  if (!short || typeof short !== 'string') return null;
+  if (isValidSessionId(short)) return short;
+  // Accept last-N-char match — convenient for mobile typing. Require ≥4 chars
+  // to avoid ambiguous matches.
+  if (short.length < 4) return null;
+  const all = listSessions({}, rootDir);
+  const match = all.find((s) => s.session_id.endsWith(short));
+  return match ? match.session_id : null;
+}
+
+async function handleCommand({ cmd, incoming, cfg, rootDir }) {
+  const name = cmd.name;
+  const rest = cmd.rest;
+
+  if (name === 'status') {
+    reconcileStaleSessions(rootDir);
+    return formatStatus({ sessions: listSessions({}, rootDir) });
+  }
+
+  if (name === 'sessions') {
+    reconcileStaleSessions(rootDir);
+    const status = rest === 'running' ? 'running' : 'all';
+    const sessions = listSessions({ status }, rootDir);
+    return formatSessionsList(sessions);
+  }
+
+  if (name === 'show') {
+    const id = resolveSessionByShortId(rest, rootDir);
+    if (!id) return formatError(`Session not found: ${rest}`);
+    const state = getSession(id, rootDir);
+    return formatSessionShow({
+      state,
+      lastEvents: readEvents(id, { tail: 5 }, rootDir),
+      lastOutput: readOutput(id, { tail: 10 }, rootDir),
+    });
+  }
+
+  if (name === 'logs') {
+    const { first, remainder } = splitFirstToken(rest);
+    const id = resolveSessionByShortId(first, rootDir);
+    if (!id) return formatError(`Session not found: ${first}`);
+    const tail = Number(remainder) || 20;
+    return formatLogs(readOutput(id, { tail }, rootDir), { tail });
+  }
+
+  if (name === 'start') {
+    const agentsCfg = loadAgentsConfig(rootDir);
+    let { first: agentName, remainder: goal } = splitFirstToken(rest);
+    if (!agentName) agentName = cfg?.telegram?.default_agent || 'claude';
+    if (!goal) return formatError('Usage: /start <agent> <goal text>');
+    if (goal.length > GOAL_MAX_LEN) return formatError(`Goal too long (${goal.length} > ${GOAL_MAX_LEN})`);
+    if (!agentsCfg.agents[agentName]) return formatError(`Unknown agent: ${agentName}`);
+    const def = agentsCfg.agents[agentName];
+    const args = [...(def.args || [])];
+    if ((def.goal_mode || 'trailing-arg') === 'trailing-arg') args.push(goal);
+    const workspace = cfg?.telegram?.default_workspace ? resolvePath(cfg.telegram.default_workspace) : rootDir;
+    const state = createSession({ agent: agentName, goal, workspacePath: workspace, command: [def.command, ...args] }, rootDir);
+    const fd = openOutputFd(state.session_id, rootDir);
+    try {
+      // F-18 Win32 PATH+PATHEXT resolution.
+      const resolved = resolveCommandPath(def.command);
+      if (!resolved.found && process.platform === 'win32') {
+        closeFd(fd);
+        updateSessionStatus(state.session_id, { status: 'failed' }, rootDir);
+        return formatError(`Agent CLI not found on PATH: ${def.command}. Install it and re-open the bot terminal.`);
+      }
+      const child = spawnAgent(resolved, args, {
+        cwd: workspace, detached: true, stdio: ['ignore', fd, fd], windowsHide: true,
+      });
+      updateSessionStatus(state.session_id, { pid: child.pid, status: 'running' }, rootDir);
+      appendEvent(state.session_id, { event: 'started', pid: child.pid, command: def.command, args, workspace, via: 'telegram' }, rootDir);
+      child.unref();
+      closeFd(fd);
+      return formatStarted({ sessionId: state.session_id, agent: agentName, goal });
+    } catch (e) {
+      closeFd(fd);
+      updateSessionStatus(state.session_id, { status: 'failed' }, rootDir);
+      return formatError(`Failed to spawn ${agentName}: ${e.message}`);
+    }
+  }
+
+  if (name === 'stop') {
+    const id = resolveSessionByShortId(rest, rootDir);
+    if (!id) return formatError(`Session not found: ${rest}`);
+    const s = getSession(id, rootDir);
+    if (!s) return formatError('Session not found.');
+    if (!s.pid) { updateSessionStatus(id, { status: 'exited' }, rootDir); return `_Already exited:_ ${id}`; }
+    try {
+      process.kill(s.pid, 'SIGTERM');
+      updateSessionStatus(id, { status: 'stopped' }, rootDir);
+      appendEvent(id, { event: 'stopped', signal: 'SIGTERM', by: `telegram:${incoming.userId}` }, rootDir);
+      return `*Stopped* \`${id}\``;
+    } catch (e) {
+      return formatError(`Cannot stop ${id}: ${e.message}`);
+    }
+  }
+
+  if (name === 'prune') {
+    const days = Number(rest) || 7;
+    const { removed, kept } = pruneSessions({ olderThanMs: days * 86400000 }, rootDir);
+    return `_Pruned ${removed.length} session(s); ${kept} kept._`;
+  }
+
+  if (name === 'help') {
+    return formatHelp(HELP_COMMANDS);
+  }
+
+  return formatError(`Unknown command: /${name}. Try /help.`);
+}
+
+// ─ Subcommand: telegram start (long-poll loop) ─
+
+export async function connectorTelegramStartCommand(opts) {
+  const rootDir = process.cwd();
+  let cfg;
+  try { cfg = loadConnectorsConfig(rootDir); }
+  catch (e) { console.error(chalk.red(`✗ ${e.message}`)); process.exit(1); }
+
+  if (!cfg.telegram || cfg.telegram.enabled !== true) {
+    console.error(chalk.red('✗ Telegram connector disabled in .dw/config/connectors.yml (set `telegram.enabled: true`).'));
+    process.exit(1);
+  }
+
+  const token = opts.token || process.env.DW_TG_BOT_TOKEN || cfg.telegram.bot_token;
+  if (!isValidTelegramToken(token)) {
+    console.error(chalk.red('✗ Invalid or missing Telegram bot token. Set DW_TG_BOT_TOKEN env, --token, or telegram.bot_token in connectors.yml.'));
+    process.exit(1);
+  }
+
+  if (!Array.isArray(cfg.telegram.allowed_user_ids) || cfg.telegram.allowed_user_ids.length === 0) {
+    console.error(chalk.yellow('⚠ telegram.allowed_user_ids is empty — bot will reject every message. Add your Telegram numeric user id to enable.'));
+  }
+
+  const client = createTelegramClient({ token, baseUrl: opts.baseUrl });
+  let me;
+  try { me = await client.getMe(); }
+  catch (e) { console.error(chalk.red(`✗ getMe failed: ${e.message}`)); process.exit(1); }
+
+  console.log(chalk.green(`  ✓  Telegram connector started`));
+  console.log(chalk.dim(`     bot: @${me.username} (id ${me.id}, token ${tokenSafeId(token)})`));
+  console.log(chalk.dim(`     allowed users: ${(cfg.telegram.allowed_user_ids || []).length}`));
+  console.log(chalk.dim(`     long-poll timeout: ${cfg.telegram.long_poll_timeout_sec || 25}s`));
+  if (opts.once) console.log(chalk.dim(`     --once: single getUpdates poll then exit`));
+  console.log();
+
+  auditLog(rootDir, { event: 'connector_started', bot_username: me.username, bot_id: me.id });
+
+  let offset = loadOffset(rootDir);
+  let running = true;
+  process.on('SIGTERM', () => { running = false; });
+  process.on('SIGINT', () => { running = false; });
+
+  const timeoutSec = Number(cfg.telegram.long_poll_timeout_sec) || 25;
+  let pollCount = 0;
+
+  while (running) {
+    let updates;
+    try {
+      updates = await client.getUpdates(offset, timeoutSec);
+    } catch (e) {
+      console.error(chalk.yellow(`  · getUpdates error (will retry): ${e.message}`));
+      await new Promise((r) => setTimeout(r, 5000));
+      continue;
+    }
+    for (const upd of updates) {
+      offset = upd.update_id + 1;
+      saveOffset(rootDir, offset);
+      try { await handleUpdate(upd, { client, cfg, rootDir }); }
+      catch (e) {
+        console.error(chalk.yellow(`  · handleUpdate error: ${e.message}`));
+        auditLog(rootDir, { event: 'handler_error', error: e.message });
+      }
+    }
+    pollCount++;
+    if (opts.once) break;
+  }
+
+  console.log(chalk.dim(`  Telegram connector stopping (processed ${pollCount} poll cycles).`));
+  auditLog(rootDir, { event: 'connector_stopped', poll_cycles: pollCount });
+}
+
+async function handleUpdate(upd, { client, cfg, rootDir }) {
+  if (!upd.message || !upd.message.text) return; // only handle text messages
+
+  const incoming = normalizeIncoming({
+    channel: 'telegram',
+    userId: upd.message.from?.id,
+    chatId: upd.message.chat?.id,
+    text: upd.message.text,
+    timestamp: new Date((upd.message.date || 0) * 1000).toISOString(),
+  });
+
+  auditLog(rootDir, { event: 'message_received', user_id: incoming.userId, chat_id: incoming.chatId, text_preview: incoming.text.slice(0, 80) });
+
+  if (!isAuthorized(cfg, incoming.userId)) {
+    await client.sendMessage(incoming.chatId, formatUnauthorized(), { parseMode: 'Markdown' });
+    auditLog(rootDir, { event: 'rejected_unauthorized', user_id: incoming.userId });
+    return;
+  }
+
+  const cmd = parseCommand(incoming.text);
+  if (!cmd) {
+    await client.sendMessage(incoming.chatId, formatHelp(HELP_COMMANDS), { parseMode: 'Markdown' });
+    return;
+  }
+
+  let reply;
+  try {
+    reply = await handleCommand({ cmd, incoming, cfg, rootDir });
+  } catch (e) {
+    reply = formatError(e.message);
+    auditLog(rootDir, { event: 'command_error', cmd: cmd.name, error: e.message });
+  }
+  await client.sendMessage(incoming.chatId, reply, { parseMode: 'Markdown' });
+  auditLog(rootDir, { event: 'command_handled', cmd: cmd.name, user_id: incoming.userId });
+}
+
+// ─ Subcommand: telegram check ─
+
+export async function connectorTelegramCheckCommand(opts) {
+  const rootDir = process.cwd();
+  let cfg;
+  try { cfg = loadConnectorsConfig(rootDir); }
+  catch (e) { console.error(chalk.red(`✗ ${e.message}`)); process.exit(1); }
+
+  const token = opts.token || process.env.DW_TG_BOT_TOKEN || cfg.telegram?.bot_token;
+  if (!isValidTelegramToken(token)) {
+    console.error(chalk.red('✗ Invalid or missing Telegram bot token.'));
+    process.exit(1);
+  }
+
+  const client = createTelegramClient({ token, baseUrl: opts.baseUrl });
+  try {
+    const me = await client.getMe();
+    console.log(chalk.green(`  ✓  Reached Telegram API`));
+    console.log(`     bot: @${me.username} (id ${me.id})`);
+    console.log(`     token id: ${tokenSafeId(token)}`);
+    console.log(`     allowed users: ${(cfg.telegram?.allowed_user_ids || []).length}`);
+    console.log(`     enabled: ${cfg.telegram?.enabled ? 'yes' : chalk.yellow('NO — start will refuse to run')}`);
+  } catch (e) {
+    console.error(chalk.red(`✗ getMe failed: ${e.message}`));
+    process.exit(1);
+  }
+}
+
+// ─ Subcommand: telegram setup (interactive wizard) ─
+
+export async function connectorTelegramSetupCommand(opts) {
+  const rootDir = process.cwd();
+  auditLog(rootDir, { event: 'setup_started' });
+
+  console.log();
+  console.log(chalk.bold('  dw connector telegram — setup wizard'));
+  console.log(chalk.dim('  ─────────────────────────────────────────'));
+  console.log(chalk.dim('  This wizard creates .dw/config/connectors.local.yml'));
+  console.log(chalk.dim('  (gitignored) with your bot token + your Telegram user id.'));
+  console.log();
+  console.log(chalk.dim('  Step 1: Get a bot token'));
+  console.log(chalk.dim('    Open Telegram → @BotFather → /newbot → follow prompts.'));
+  console.log(chalk.dim('    BotFather replies with a token like 123456789:AAH...'));
+  console.log();
+
+  // Token prompt — password type masks input.
+  let token = opts.token || process.env.DW_TG_BOT_TOKEN;
+  if (!token) {
+    const ans = await prompt({
+      type: 'password',
+      name: 'token',
+      message: 'Paste your bot token (hidden):',
+    });
+    token = (ans.token || '').trim();
+  }
+
+  if (!isValidTelegramToken(token)) {
+    auditLog(rootDir, { event: 'setup_failed', reason: 'invalid_token_format' });
+    console.error(chalk.red(`✗ Invalid token format. Expected: <numeric_id>:<secret>`));
+    process.exit(1);
+  }
+
+  // Verify token via getMe.
+  const client = createTelegramClient({ token, baseUrl: opts.baseUrl });
+  let me;
+  try { me = await client.getMe(); }
+  catch (e) {
+    auditLog(rootDir, { event: 'setup_failed', reason: 'getme_failed', error: e.message });
+    console.error(chalk.red(`✗ getMe failed: ${e.message}`));
+    process.exit(1);
+  }
+  auditLog(rootDir, { event: 'setup_token_verified', bot_username: me.username, bot_id: me.id, token_safe_id: tokenSafeId(token) });
+
+  console.log(chalk.green(`  ✓  Token works — bot is @${me.username} (id ${me.id})`));
+  console.log();
+  console.log(chalk.dim('  Step 2: Discover your Telegram user id'));
+  console.log(chalk.dim(`    Open Telegram → search @${me.username} → send any message (e.g. /start)`));
+  console.log();
+  console.log(chalk.dim('  Waiting for a message (timeout 90s)…'));
+
+  // Poll briefly to capture the first incoming user id.
+  const deadline = Date.now() + 90_000;
+  let discoveredUserId = null;
+  let offset = 0;
+  while (Date.now() < deadline && !discoveredUserId) {
+    const remaining = Math.max(1, Math.ceil((deadline - Date.now()) / 1000));
+    const pollTimeout = Math.min(25, remaining);
+    let updates;
+    try { updates = await client.getUpdates(offset, pollTimeout); }
+    catch (e) {
+      console.error(chalk.yellow(`  · getUpdates: ${e.message}; retrying…`));
+      await new Promise((r) => setTimeout(r, 2000));
+      continue;
+    }
+    for (const upd of updates) {
+      offset = upd.update_id + 1;
+      if (upd.message && upd.message.from && upd.message.from.id) {
+        discoveredUserId = upd.message.from.id;
+        const fromName = upd.message.from.username
+          ? `@${upd.message.from.username}`
+          : `${upd.message.from.first_name || ''} ${upd.message.from.last_name || ''}`.trim();
+        console.log(chalk.green(`  ✓  Got message from ${fromName} (user id ${discoveredUserId})`));
+        // Reply to confirm
+        try {
+          await client.sendMessage(upd.message.chat.id,
+            `*Setup complete!* Your user id (\`${discoveredUserId}\`) is now on the allow-list.\n\nTry \`/help\` next.`,
+            { parseMode: 'Markdown' });
+        } catch { /* best-effort reply */ }
+        break;
+      }
+    }
+  }
+
+  if (!discoveredUserId) {
+    auditLog(rootDir, { event: 'setup_failed', reason: 'no_message_in_90s' });
+    console.error(chalk.yellow(`  · No message received in 90s.`));
+    console.log(chalk.dim(`     You can still configure manually by editing ${CONNECTORS_LOCAL_PATH}`));
+    console.log(chalk.dim(`     and adding your numeric user id (find it via @userinfobot).`));
+    process.exit(2);
+  }
+
+  // Write local config.
+  const path = writeLocalConfig(rootDir, {
+    telegram: {
+      enabled: true,
+      bot_token: token,
+      allowed_user_ids: [discoveredUserId],
+    },
+  });
+  auditLog(rootDir, { event: 'setup_completed', bot_username: me.username, bot_id: me.id, discovered_user_id: discoveredUserId, wrote: CONNECTORS_LOCAL_PATH });
+
+  console.log();
+  console.log(chalk.green('  ✓  Setup complete.'));
+  console.log(chalk.dim(`     wrote: ${path}`));
+  console.log(chalk.dim(`     bot:   @${me.username}`));
+  console.log(chalk.dim(`     allow: [${discoveredUserId}]`));
+  console.log();
+  console.log(chalk.bold('  Next:'));
+  console.log(chalk.dim('    dw connector telegram start     # leave running; Ctrl+C to stop'));
+  console.log();
+}
+
+// ─ Subcommand: list ─
+
+export async function connectorListCommand() {
+  const rootDir = process.cwd();
+  let cfg;
+  try { cfg = loadConnectorsConfig(rootDir); }
+  catch (e) { console.log(chalk.dim(`  (no connectors config — copy template from dw-kit repo)`)); return; }
+
+  console.log();
+  console.log(chalk.bold('  Configured connectors'));
+  for (const [name, conf] of Object.entries(cfg)) {
+    if (name === 'schema_version' || typeof conf !== 'object') continue;
+    const status = conf.enabled ? chalk.green('enabled') : chalk.gray('disabled');
+    console.log(`    ${name}  ${status}`);
+  }
+  console.log();
+}