opensquid 0.5.395

package/dist/chat/env-token.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Telegram / Discord / Slack bot-token loading from env var + .env
+ * file (0.7.5+, #148).
+ *
+ * Priority (highest first):
+ *   1. process.env.OPENSQUID_TELEGRAM_BOT_TOKEN (or _DISCORD_, _SLACK_)
+ *   2. .env file (first match wins):
+ *      - $OPENSQUID_ENV_FILE
+ *      - ~/.loop/.env
+ *      - ~/.opensquid/.env
+ *      - <cwd>/.env
+ *   3. ~/.opensquid/config.json chat_connections.<platform>.bot_token
+ *
+ * The .env parser supports standard KEY=VALUE lines AND a tolerant
+ * "bare token" fallback (single non-comment line, no `=`) — the user
+ * may save just the token. Bare tokens are treated as
+ * OPENSQUID_TELEGRAM_BOT_TOKEN.
+ *
+ * NEVER logs the token value. Only logs which SOURCE the active token
+ * came from, so operators can debug "which bot is this daemon
+ * actually using" without leaking the secret.
+ */
+export type EnvKey = "OPENSQUID_TELEGRAM_BOT_TOKEN" | "OPENSQUID_DISCORD_BOT_TOKEN" | "OPENSQUID_SLACK_BOT_TOKEN" | "OPENSQUID_SLACK_APP_TOKEN";
+export type EnvSource = "env" | "env-file" | "config-json" | "missing";
+export interface TokenLookup {
+    value: string | undefined;
+    source: EnvSource;
+    /** Path to the .env file used (only set when source === "env-file"). */
+    env_file_path?: string;
+}
+/**
+ * Resolve a token by priority: process.env → .env file → config.json
+ * fallback (caller-supplied). Returns the value AND the source it
+ * came from so the caller can log the source without exposing the
+ * value.
+ */
+export declare function resolveToken(key: EnvKey, configJsonFallback: string | undefined): Promise<TokenLookup>;
+/**
+ * Find the first existing .env file in the search order. Returns null
+ * if none exist.
+ */
+export declare function locateEnvFile(): Promise<string | null>;
+/**
+ * Parse a .env file into a flat string map. Supports:
+ *
+ *   - `KEY=VALUE` lines (standard dotenv format)
+ *   - `KEY="quoted value"` (double-quoted)
+ *   - `KEY='quoted value'` (single-quoted)
+ *   - `#` comments + blank lines
+ *   - Bare-token fallback: if the file has exactly ONE non-comment
+ *     line and that line has no `=`, treat it as
+ *     OPENSQUID_TELEGRAM_BOT_TOKEN (most common shape for "user
+ *     saved just the token")
+ *
+ * Caches by path to avoid re-reading on every call.
+ */
+export declare function loadEnvFile(envPath: string): Promise<Record<string, string>>;
+/** Test-only: clear the .env cache so subsequent loads re-read disk. */
+export declare function _clearEnvFileCache(): void;
+//# sourceMappingURL=env-token.d.ts.map

package/dist/chat/env-token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-token.d.ts","sourceRoot":"","sources":["../../src.legacy/chat/env-token.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAMH,MAAM,MAAM,MAAM,GACd,8BAA8B,GAC9B,6BAA6B,GAC7B,2BAA2B,GAC3B,2BAA2B,CAAC;AAEhC,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,UAAU,GAAG,aAAa,GAAG,SAAS,CAAC;AAEvE,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,MAAM,EAAE,SAAS,CAAC;IAClB,wEAAwE;IACxE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAKD;;;;;GAKG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,MAAM,EACX,kBAAkB,EAAE,MAAM,GAAG,SAAS,GACrC,OAAO,CAAC,WAAW,CAAC,CAuBtB;AAED;;;GAGG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiB5D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAwClF;AAED,wEAAwE;AACxE,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}

package/dist/chat/env-token.js

@@ -0,0 +1,137 @@
+/**
+ * Telegram / Discord / Slack bot-token loading from env var + .env
+ * file (0.7.5+, #148).
+ *
+ * Priority (highest first):
+ *   1. process.env.OPENSQUID_TELEGRAM_BOT_TOKEN (or _DISCORD_, _SLACK_)
+ *   2. .env file (first match wins):
+ *      - $OPENSQUID_ENV_FILE
+ *      - ~/.loop/.env
+ *      - ~/.opensquid/.env
+ *      - <cwd>/.env
+ *   3. ~/.opensquid/config.json chat_connections.<platform>.bot_token
+ *
+ * The .env parser supports standard KEY=VALUE lines AND a tolerant
+ * "bare token" fallback (single non-comment line, no `=`) — the user
+ * may save just the token. Bare tokens are treated as
+ * OPENSQUID_TELEGRAM_BOT_TOKEN.
+ *
+ * NEVER logs the token value. Only logs which SOURCE the active token
+ * came from, so operators can debug "which bot is this daemon
+ * actually using" without leaking the secret.
+ */
+import { promises as fs } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+/** In-memory cache for parsed .env files. Invalidated on each new process. */
+let envFileCache = null;
+/**
+ * Resolve a token by priority: process.env → .env file → config.json
+ * fallback (caller-supplied). Returns the value AND the source it
+ * came from so the caller can log the source without exposing the
+ * value.
+ */
+export async function resolveToken(key, configJsonFallback) {
+    // 1. process.env
+    const envVal = process.env[key];
+    if (envVal && envVal.trim()) {
+        return { value: envVal.trim(), source: "env" };
+    }
+    // 2. .env file
+    const envFile = await locateEnvFile();
+    if (envFile) {
+        const parsed = await loadEnvFile(envFile);
+        const fileVal = parsed[key];
+        if (fileVal && fileVal.trim()) {
+            return { value: fileVal.trim(), source: "env-file", env_file_path: envFile };
+        }
+    }
+    // 3. config.json fallback
+    if (configJsonFallback && configJsonFallback.trim()) {
+        return { value: configJsonFallback.trim(), source: "config-json" };
+    }
+    return { value: undefined, source: "missing" };
+}
+/**
+ * Find the first existing .env file in the search order. Returns null
+ * if none exist.
+ */
+export async function locateEnvFile() {
+    const candidates = [];
+    if (process.env.OPENSQUID_ENV_FILE)
+        candidates.push(process.env.OPENSQUID_ENV_FILE);
+    const home = os.homedir();
+    candidates.push(path.join(home, ".loop", ".env"));
+    candidates.push(path.join(home, ".opensquid", ".env"));
+    candidates.push(path.join(process.cwd(), ".env"));
+    for (const c of candidates) {
+        try {
+            await fs.access(c);
+            return c;
+        }
+        catch {
+            // not present, keep looking
+        }
+    }
+    return null;
+}
+/**
+ * Parse a .env file into a flat string map. Supports:
+ *
+ *   - `KEY=VALUE` lines (standard dotenv format)
+ *   - `KEY="quoted value"` (double-quoted)
+ *   - `KEY='quoted value'` (single-quoted)
+ *   - `#` comments + blank lines
+ *   - Bare-token fallback: if the file has exactly ONE non-comment
+ *     line and that line has no `=`, treat it as
+ *     OPENSQUID_TELEGRAM_BOT_TOKEN (most common shape for "user
+ *     saved just the token")
+ *
+ * Caches by path to avoid re-reading on every call.
+ */
+export async function loadEnvFile(envPath) {
+    if (envFileCache && envFileCache.path === envPath) {
+        return envFileCache.parsed;
+    }
+    const raw = await fs.readFile(envPath, "utf8");
+    const lines = raw.split(/\r?\n/);
+    const out = {};
+    const nonComment = [];
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        nonComment.push(trimmed);
+    }
+    let hadKeyValue = false;
+    for (const line of nonComment) {
+        const eq = line.indexOf("=");
+        if (eq === -1)
+            continue;
+        hadKeyValue = true;
+        const key = line.slice(0, eq).trim();
+        let value = line.slice(eq + 1).trim();
+        // Strip surrounding quotes (single or double).
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        if (key)
+            out[key] = value;
+    }
+    // Bare-token fallback: exactly one non-comment line, no =, looks
+    // like a Telegram bot token. Treat as OPENSQUID_TELEGRAM_BOT_TOKEN.
+    if (!hadKeyValue && nonComment.length === 1) {
+        const bare = nonComment[0];
+        // Telegram tokens look like <digits>:<alphanum_-> (47+ chars total).
+        if (/^\d+:[A-Za-z0-9_-]{20,}$/.test(bare)) {
+            out.OPENSQUID_TELEGRAM_BOT_TOKEN = bare;
+        }
+    }
+    envFileCache = { path: envPath, parsed: out };
+    return out;
+}
+/** Test-only: clear the .env cache so subsequent loads re-read disk. */
+export function _clearEnvFileCache() {
+    envFileCache = null;
+}

package/dist/chat/env-token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-token.js","sourceRoot":"","sources":["../../src.legacy/chat/env-token.ts"],"names":[],"mappings":"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"}

package/dist/chat/env-token.test.js

@@ -0,0 +1,160 @@
+/**
+ * env-token.ts tests (#148): priority + .env parsing.
+ */
+import { promises as fs } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { _clearEnvFileCache, loadEnvFile, locateEnvFile, resolveToken } from "./env-token.js";
+let tmpDir;
+const SAVED_ENV = {};
+function saveEnv(...keys) {
+    for (const k of keys)
+        SAVED_ENV[k] = process.env[k];
+}
+function restoreEnv() {
+    for (const [k, v] of Object.entries(SAVED_ENV)) {
+        if (v === undefined)
+            delete process.env[k];
+        else
+            process.env[k] = v;
+    }
+}
+beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "opensquid-envtoken-"));
+    saveEnv("OPENSQUID_TELEGRAM_BOT_TOKEN", "OPENSQUID_DISCORD_BOT_TOKEN", "OPENSQUID_SLACK_BOT_TOKEN", "OPENSQUID_SLACK_APP_TOKEN", "OPENSQUID_ENV_FILE", "HOME");
+    // Wipe inherited values so tests run from a known empty state.
+    delete process.env.OPENSQUID_TELEGRAM_BOT_TOKEN;
+    delete process.env.OPENSQUID_DISCORD_BOT_TOKEN;
+    delete process.env.OPENSQUID_SLACK_BOT_TOKEN;
+    delete process.env.OPENSQUID_SLACK_APP_TOKEN;
+    delete process.env.OPENSQUID_ENV_FILE;
+    // Override HOME so the .env candidate paths (~/.loop/.env etc) point
+    // at the empty tmpdir, not the real home directory where the user
+    // may have a real .env that would taint the test.
+    process.env.HOME = tmpDir;
+    _clearEnvFileCache();
+});
+afterEach(async () => {
+    restoreEnv();
+    _clearEnvFileCache();
+    await fs.rm(tmpDir, { recursive: true, force: true });
+});
+describe("loadEnvFile — parsing", () => {
+    it("parses standard KEY=VALUE lines", async () => {
+        const p = path.join(tmpDir, ".env");
+        await fs.writeFile(p, "OPENSQUID_TELEGRAM_BOT_TOKEN=1234:abcdef\nSOMETHING_ELSE=value\n");
+        const parsed = await loadEnvFile(p);
+        expect(parsed.OPENSQUID_TELEGRAM_BOT_TOKEN).toBe("1234:abcdef");
+        expect(parsed.SOMETHING_ELSE).toBe("value");
+    });
+    it("strips surrounding double quotes", async () => {
+        const p = path.join(tmpDir, ".env");
+        await fs.writeFile(p, 'KEY="quoted value with spaces"\n');
+        const parsed = await loadEnvFile(p);
+        expect(parsed.KEY).toBe("quoted value with spaces");
+    });
+    it("strips surrounding single quotes", async () => {
+        const p = path.join(tmpDir, ".env");
+        await fs.writeFile(p, "KEY='quoted value'\n");
+        const parsed = await loadEnvFile(p);
+        expect(parsed.KEY).toBe("quoted value");
+    });
+    it("ignores blank lines and # comments", async () => {
+        const p = path.join(tmpDir, ".env");
+        await fs.writeFile(p, "# top comment\n\nKEY=value\n# trailing comment\n");
+        const parsed = await loadEnvFile(p);
+        expect(parsed).toEqual({ KEY: "value" });
+    });
+    it("treats a single bare Telegram-token line as OPENSQUID_TELEGRAM_BOT_TOKEN", async () => {
+        const p = path.join(tmpDir, ".env");
+        await fs.writeFile(p, "8684088310:AAFgYblhOAadDN_i5osTtfkSTAgwlnneU-4\n");
+        const parsed = await loadEnvFile(p);
+        expect(parsed.OPENSQUID_TELEGRAM_BOT_TOKEN).toBe("8684088310:AAFgYblhOAadDN_i5osTtfkSTAgwlnneU-4");
+    });
+    it("does NOT treat a bare line as a token if it doesn't match the token shape", async () => {
+        const p = path.join(tmpDir, ".env");
+        await fs.writeFile(p, "just-some-random-text\n");
+        const parsed = await loadEnvFile(p);
+        expect(parsed.OPENSQUID_TELEGRAM_BOT_TOKEN).toBeUndefined();
+    });
+    it("does NOT use bare-line fallback if KEY=VALUE lines are also present", async () => {
+        const p = path.join(tmpDir, ".env");
+        await fs.writeFile(p, "OTHER=ok\n1234:abcdefghij1234567890\n");
+        const parsed = await loadEnvFile(p);
+        expect(parsed.OPENSQUID_TELEGRAM_BOT_TOKEN).toBeUndefined();
+        expect(parsed.OTHER).toBe("ok");
+    });
+});
+describe("locateEnvFile — search order", () => {
+    it("returns the path given by OPENSQUID_ENV_FILE if it exists", async () => {
+        const p = path.join(tmpDir, "custom.env");
+        await fs.writeFile(p, "KEY=value\n");
+        process.env.OPENSQUID_ENV_FILE = p;
+        expect(await locateEnvFile()).toBe(p);
+    });
+    it("returns null if no .env exists in any candidate location", async () => {
+        // Override HOME so the function looks at our empty tmpDir
+        const savedHome = process.env.HOME;
+        process.env.HOME = tmpDir;
+        try {
+            const r = await locateEnvFile();
+            // Could still hit a cwd .env in the actual project — accept that
+            // and only assert null when no env file at all.
+            if (r) {
+                expect(r).not.toBe(path.join(tmpDir, ".loop", ".env"));
+                expect(r).not.toBe(path.join(tmpDir, ".opensquid", ".env"));
+            }
+        }
+        finally {
+            if (savedHome)
+                process.env.HOME = savedHome;
+            else
+                delete process.env.HOME;
+        }
+    });
+});
+describe("resolveToken — priority order", () => {
+    it("returns env-var value with source='env' when set", async () => {
+        process.env.OPENSQUID_TELEGRAM_BOT_TOKEN = "from-env";
+        const r = await resolveToken("OPENSQUID_TELEGRAM_BOT_TOKEN", "from-config");
+        expect(r.value).toBe("from-env");
+        expect(r.source).toBe("env");
+    });
+    it("falls back to .env file when env-var unset", async () => {
+        const p = path.join(tmpDir, ".env");
+        await fs.writeFile(p, "OPENSQUID_TELEGRAM_BOT_TOKEN=from-file\n");
+        process.env.OPENSQUID_ENV_FILE = p;
+        const r = await resolveToken("OPENSQUID_TELEGRAM_BOT_TOKEN", "from-config");
+        expect(r.value).toBe("from-file");
+        expect(r.source).toBe("env-file");
+        expect(r.env_file_path).toBe(p);
+    });
+    it("falls back to config.json value when neither env-var nor .env set", async () => {
+        const r = await resolveToken("OPENSQUID_TELEGRAM_BOT_TOKEN", "from-config");
+        expect(r.value).toBe("from-config");
+        expect(r.source).toBe("config-json");
+    });
+    it("returns missing when no source has a value", async () => {
+        const r = await resolveToken("OPENSQUID_TELEGRAM_BOT_TOKEN", undefined);
+        expect(r.value).toBeUndefined();
+        expect(r.source).toBe("missing");
+    });
+    it("env-var WINS over .env even when both are set", async () => {
+        process.env.OPENSQUID_TELEGRAM_BOT_TOKEN = "from-env";
+        const p = path.join(tmpDir, ".env");
+        await fs.writeFile(p, "OPENSQUID_TELEGRAM_BOT_TOKEN=from-file\n");
+        process.env.OPENSQUID_ENV_FILE = p;
+        const r = await resolveToken("OPENSQUID_TELEGRAM_BOT_TOKEN", "from-config");
+        expect(r.value).toBe("from-env");
+        expect(r.source).toBe("env");
+    });
+    it(".env WINS over config.json even when both have values", async () => {
+        const p = path.join(tmpDir, ".env");
+        await fs.writeFile(p, "OPENSQUID_TELEGRAM_BOT_TOKEN=from-file\n");
+        process.env.OPENSQUID_ENV_FILE = p;
+        const r = await resolveToken("OPENSQUID_TELEGRAM_BOT_TOKEN", "from-config");
+        expect(r.value).toBe("from-file");
+        expect(r.source).toBe("env-file");
+    });
+});

package/dist/chat/factory.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Build a ChatGateway from `~/.opensquid/config.json`'s
+ * `chat_connections` block. Skips adapters whose tokens are missing —
+ * opensquid works with zero, one, or all three chat platforms wired.
+ *
+ * Per-platform adapter modules (telegram/discord/slack) are imported
+ * dynamically here so the factory doesn't pull all three SDK trees
+ * into the cold-start path. Each adapter's own dynamic-import of its
+ * SDK runs only inside `.start()`.
+ */
+import { ChatGateway } from "./gateway.js";
+import type { ChatConnectionsConfig } from "./config.js";
+export interface BuildOptions {
+    dataRoot?: string;
+    /** Inject a pre-loaded config (skips disk read). For tests. */
+    config?: ChatConnectionsConfig;
+}
+export interface BuildResult {
+    gateway: ChatGateway;
+    /** Platforms that ended up in the gateway. */
+    activated: Array<"telegram" | "discord" | "slack">;
+    /** Validation issues — surfaced but non-fatal for partial activation. */
+    issues: Array<{
+        platform: string;
+        field: string;
+        problem: string;
+    }>;
+}
+export declare function buildChatGateway(opts?: BuildOptions): Promise<BuildResult>;
+//# sourceMappingURL=factory.d.ts.map

package/dist/chat/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../src.legacy/chat/factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,WAAW,EAAoB,MAAM,cAAc,CAAC;AAE7D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEzD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,qBAAqB,CAAC;CAChC;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,WAAW,CAAC;IACrB,8CAA8C;IAC9C,SAAS,EAAE,KAAK,CAAC,UAAU,GAAG,SAAS,GAAG,OAAO,CAAC,CAAC;IACnD,yEAAyE;IACzE,MAAM,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrE;AAED,wBAAsB,gBAAgB,CAAC,IAAI,GAAE,YAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CA+CpF"}

package/dist/chat/factory.js

@@ -0,0 +1,50 @@
+/**
+ * Build a ChatGateway from `~/.opensquid/config.json`'s
+ * `chat_connections` block. Skips adapters whose tokens are missing —
+ * opensquid works with zero, one, or all three chat platforms wired.
+ *
+ * Per-platform adapter modules (telegram/discord/slack) are imported
+ * dynamically here so the factory doesn't pull all three SDK trees
+ * into the cold-start path. Each adapter's own dynamic-import of its
+ * SDK runs only inside `.start()`.
+ */
+import { ChatGateway, ChatGatewayError } from "./gateway.js";
+import { loadChatConfig, validateChatConfig } from "./config.js";
+export async function buildChatGateway(opts = {}) {
+    const config = opts.config ?? (await loadChatConfig(opts.dataRoot));
+    const issues = validateChatConfig(config);
+    const adapters = [];
+    const activated = [];
+    // Each block: only activate if (a) config block exists AND (b) no
+    // validation issue against this platform's tokens. An issue here
+    // means the user has a partial config (e.g. typo'd token) — better
+    // to skip with a logged warning than throw and prevent the other
+    // adapters from working.
+    if (config.telegram && !issues.some((i) => i.platform === "telegram")) {
+        const { TelegramAdapter } = await import("./adapters/telegram.js");
+        adapters.push(new TelegramAdapter(config.telegram));
+        activated.push("telegram");
+    }
+    if (config.discord && !issues.some((i) => i.platform === "discord")) {
+        const { DiscordAdapter } = await import("./adapters/discord.js");
+        adapters.push(new DiscordAdapter(config.discord));
+        activated.push("discord");
+    }
+    if (config.slack && !issues.some((i) => i.platform === "slack")) {
+        const { SlackAdapter } = await import("./adapters/slack.js");
+        adapters.push(new SlackAdapter(config.slack));
+        activated.push("slack");
+    }
+    // Throw when the user clearly mis-configured a token. All three
+    // platforms are now implemented (v0.7c), so any validation issue
+    // against a configured platform is a real problem.
+    const blockingIssues = issues.filter((i) => (i.platform === "telegram" && !!config.telegram) ||
+        (i.platform === "discord" && !!config.discord) ||
+        (i.platform === "slack" && !!config.slack));
+    if (blockingIssues.length > 0 && adapters.length === 0) {
+        throw new ChatGatewayError("chat connections configured but failed validation — see issues", `validation: ${blockingIssues
+            .map((i) => `${i.platform}.${i.field}: ${i.problem}`)
+            .join("; ")}`);
+    }
+    return { gateway: new ChatGateway(adapters), activated, issues };
+}

package/dist/chat/factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../src.legacy/chat/factory.ts"],"names":[],"mappings":"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"}

package/dist/chat/factory.test.js

@@ -0,0 +1,55 @@
+import { describe, expect, it, vi } from "vitest";
+import { ChatGatewayError } from "./gateway.js";
+import { buildChatGateway } from "./factory.js";
+describe("buildChatGateway", () => {
+    it("returns an empty gateway when no chat config is present", async () => {
+        const result = await buildChatGateway({ config: {} });
+        expect(result.activated).toEqual([]);
+        expect(result.gateway.activePlatforms()).toEqual([]);
+        expect(result.issues).toEqual([]);
+    });
+    it("v0.7c: activates all three platforms when all are validly configured", async () => {
+        const result = await buildChatGateway({
+            config: {
+                telegram: { bot_token: "123456:ABC-DEF1234" },
+                discord: { bot_token: "MTAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" },
+                slack: { bot_token: "xoxb-1-2-3", app_token: "xapp-1-2-3" },
+            },
+        });
+        expect(result.activated.sort()).toEqual(["discord", "slack", "telegram"]);
+    });
+    it("v0.7c: activates discord + slack independently of telegram", async () => {
+        const result = await buildChatGateway({
+            config: {
+                discord: { bot_token: "MTAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" },
+                slack: { bot_token: "xoxb-1-2-3", app_token: "xapp-1-2-3" },
+            },
+        });
+        expect(result.activated.sort()).toEqual(["discord", "slack"]);
+    });
+    it("activates telegram when its config block is valid", async () => {
+        const result = await buildChatGateway({
+            config: { telegram: { bot_token: "123456:ABC-DEF1234" } },
+        });
+        expect(result.activated).toEqual(["telegram"]);
+        expect(result.gateway.activePlatforms()).toEqual(["telegram"]);
+    });
+    it("skips telegram with invalid token format AND throws because no other adapter activated", async () => {
+        await expect(buildChatGateway({
+            config: { telegram: { bot_token: "not-a-real-format" } },
+        })).rejects.toThrow(ChatGatewayError);
+    });
+    it("partial config: telegram valid + slack invalid → telegram activates, slack issue logged", async () => {
+        const warn = vi.spyOn(console, "warn").mockImplementation(() => { });
+        const result = await buildChatGateway({
+            config: {
+                telegram: { bot_token: "123456:ABC-DEF1234" },
+                // slack with wrong-shape tokens triggers validation issues
+                slack: { bot_token: "wrong-prefix", app_token: "also-wrong" },
+            },
+        });
+        expect(result.activated).toEqual(["telegram"]);
+        expect(result.issues.find((i) => i.platform === "slack")).toBeTruthy();
+        warn.mockRestore();
+    });
+});