@signal4/s4 2.0.0

package/dist/cli.js

@@ -0,0 +1,737 @@
+/** Signal4 CLI — terminal interface sharing handlers with the MCP server. */
+import { applyConfig } from "./config.js";
+import { HANDLERS } from "./handlers/registry.js";
+import * as client from "./client.js";
+import { writeFileSync, mkdirSync, existsSync, chmodSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { createInterface } from "node:readline/promises";
+function parseArgs(argv, specs) {
+    const flags = {};
+    const positionals = [];
+    // Apply defaults
+    for (const s of specs)
+        flags[s.name] = s.default ?? (s.type === "boolean" ? false : s.type === "number" ? 0 : "");
+    // Build lookup: --name and -alias -> spec
+    const lookup = new Map();
+    for (const s of specs) {
+        lookup.set(`--${s.name}`, s);
+        if (s.alias)
+            lookup.set(`-${s.alias}`, s);
+    }
+    let i = 0;
+    while (i < argv.length) {
+        const arg = argv[i];
+        const spec = lookup.get(arg);
+        if (spec) {
+            if (spec.type === "boolean") {
+                flags[spec.name] = true;
+            }
+            else {
+                const val = argv[++i];
+                flags[spec.name] = spec.type === "number" ? Number(val) : (val ?? "");
+            }
+        }
+        else if (arg.startsWith("-")) {
+            // Unknown flag — skip
+        }
+        else {
+            positionals.push(arg);
+        }
+        i++;
+    }
+    return { positionals, flags };
+}
+// ---------------------------------------------------------------------------
+// Shared flag specs
+// ---------------------------------------------------------------------------
+const FLAG_DAYS = { name: "days", alias: "d", type: "number", default: 30 };
+const FLAG_LIMIT = { name: "limit", alias: "n", type: "number", default: 20 };
+const FLAG_OFFSET = { name: "offset", alias: "o", type: "number", default: 0 };
+const FLAG_SPEAKER = { name: "speaker", alias: "s", type: "string" };
+const FLAG_CHANNEL = { name: "channel", alias: "c", type: "string" };
+const FLAG_LANGUAGE = { name: "language", alias: "l", type: "string" };
+const FLAG_MODE = { name: "mode", alias: "m", type: "string", default: "semantic" };
+const FLAG_SKIP_CACHE = { name: "skip-cache", type: "boolean" };
+const FLAG_JSON = { name: "json", type: "boolean" };
+function daysRange(days) {
+    const end = new Date().toISOString().slice(0, 10);
+    const start = new Date(Date.now() - days * 86400000).toISOString().slice(0, 10);
+    return { start_date: start, end_date: end };
+}
+function print(text) {
+    process.stdout.write(text + "\n");
+}
+function printJson(data) {
+    print(JSON.stringify(data, null, 2));
+}
+async function runHandler(tool, params) {
+    const handler = HANDLERS[tool];
+    if (!handler) {
+        print(`Error: handler "${tool}" not found.`);
+        process.exit(1);
+    }
+    const result = await handler(params);
+    if (result.isError) {
+        process.stderr.write((result.content[0]?.text ?? "Unknown error") + "\n");
+        process.exit(1);
+    }
+    print(result.content[0]?.text ?? "");
+}
+const COMMANDS = {
+    search: {
+        tool: "search_quotes",
+        description: "Search quotes by topic and/or speaker",
+        specs: [FLAG_SPEAKER, FLAG_CHANNEL, FLAG_DAYS, FLAG_MODE, FLAG_LIMIT, FLAG_OFFSET, FLAG_LANGUAGE,
+            { name: "sort", type: "string", default: "relevance" },
+            { name: "count", type: "boolean" },
+            { name: "speaker-id", type: "number" },
+            { name: "start", type: "string" }, { name: "end", type: "string" },
+            FLAG_JSON],
+        run: async (args, json) => {
+            const [topic] = args.positionals;
+            const f = args.flags;
+            const days = Number(f.days) || 30;
+            const dr = f.start ? { start_date: f.start, end_date: f.end || new Date().toISOString().slice(0, 10) } : daysRange(days);
+            const params = {
+                topic, speaker_name: f.speaker || undefined,
+                speaker_id: Number(f["speaker-id"]) || undefined,
+                channel_name: f.channel || undefined,
+                days, ...dr,
+                mode: f.mode, limit: Number(f.limit), offset: Number(f.offset),
+                count_only: f.count, sort: f.sort,
+            };
+            if (json)
+                return printJson(await client.searchQuotes({
+                    topic: params.topic, speaker_name: params.speaker_name,
+                    speaker_identity_id: params.speaker_id, channel_name: params.channel_name,
+                    start_date: params.start_date, end_date: params.end_date,
+                    mode: params.mode !== "semantic" ? params.mode : undefined,
+                    limit: params.count_only ? 1 : Math.min(params.limit, 50), offset: params.offset,
+                }));
+            await runHandler("search_quotes", params);
+        },
+    },
+    claims: {
+        tool: "search_claims",
+        description: "Search extracted claims",
+        specs: [{ name: "entity", alias: "e", type: "string" }, FLAG_SPEAKER, FLAG_CHANNEL,
+            { name: "category", type: "string" }, { name: "stance", type: "string" },
+            FLAG_LANGUAGE, FLAG_MODE,
+            { name: "sort", type: "string", default: "relevance" },
+            { name: "min-obs", type: "number", default: 1 },
+            FLAG_DAYS, FLAG_LIMIT, FLAG_OFFSET, FLAG_JSON],
+        run: async (args, json) => {
+            const [topic] = args.positionals;
+            const f = args.flags;
+            const days = Number(f.days) || 30;
+            const params = {
+                topic, entity: f.entity || undefined,
+                speaker_name: f.speaker || undefined,
+                channel_name: f.channel || undefined,
+                category: f.category || undefined,
+                stance: f.stance || undefined,
+                language: f.language || undefined,
+                days, mode: f.mode,
+                sort: f.sort, min_observations: Number(f["min-obs"]) || 1,
+                limit: Number(f.limit), offset: Number(f.offset),
+            };
+            if (json)
+                return printJson(await client.searchClaims({
+                    topic: params.topic, entity: params.entity, speaker_name: params.speaker_name,
+                    channel_names: params.channel_name ? [params.channel_name] : undefined,
+                    primary_topic: params.category, stance: params.stance, language: params.language,
+                    days: params.days, mode: params.mode, sort: params.sort,
+                    min_observations: params.min_observations > 1 ? params.min_observations : undefined,
+                    limit: Math.min(params.limit, 50), offset: params.offset,
+                }));
+            await runHandler("search_claims", params);
+        },
+    },
+    trend: {
+        tool: "detect_trend",
+        description: "Detect topic volume trends",
+        specs: [{ name: "recent", type: "number", default: 7 },
+            { name: "baseline", type: "number", default: 30 },
+            { name: "min-similarity", type: "number" }, FLAG_JSON],
+        run: async (args, json) => {
+            const [topic] = args.positionals;
+            if (!topic) {
+                print("Error: topic is required.");
+                process.exit(1);
+            }
+            const f = args.flags;
+            const params = {
+                topic, recent_days: Number(f.recent) || 7, baseline_days: Number(f.baseline) || 30,
+                min_similarity: Number(f["min-similarity"]) || undefined,
+            };
+            if (json)
+                return printJson(await client.detectTrend(params));
+            await runHandler("detect_trend", params);
+        },
+    },
+    speaker: {
+        tool: "find_speakers",
+        description: "Speaker search, profile, or discourse",
+        specs: [FLAG_DAYS, FLAG_LIMIT, FLAG_OFFSET,
+            { name: "segments", type: "boolean" }, FLAG_JSON],
+        run: async (args, json) => {
+            const [identity, topic] = args.positionals;
+            if (!identity) {
+                print("Error: speaker name or ID required.");
+                process.exit(1);
+            }
+            const f = args.flags;
+            const isId = /^\d+$/.test(identity);
+            const days = Number(f.days) || 30;
+            const limit = Number(f.limit) || 20;
+            // Profile by ID
+            if (isId) {
+                const sid = Number(identity);
+                if (f.segments) {
+                    const params = { speaker_id: sid, sort: "chronological", days, limit, offset: Number(f.offset) };
+                    if (json)
+                        return printJson(await client.getSpeakerSegments({ identity_id: sid, days, limit, offset: Number(f.offset) }));
+                    await runHandler("search_quotes", params);
+                }
+                else if (topic) {
+                    const params = { speaker_id: sid, topic, days, limit };
+                    if (json)
+                        return printJson(await client.searchSpeakerSegments({ identity_id: sid, query: topic, days, limit }));
+                    await runHandler("search_quotes", params);
+                }
+                else {
+                    if (json)
+                        return printJson(await client.getSpeaker(sid));
+                    await runHandler("get_speaker", { speaker_id: sid });
+                }
+                return;
+            }
+            // Segments by name
+            if (f.segments) {
+                const params = { speaker_name: identity, sort: "chronological", days, limit, offset: Number(f.offset) };
+                if (json) {
+                    const byName = await client.getSpeakerByName(identity);
+                    const sid = byName.speaker_id ?? byName.id;
+                    if (sid)
+                        return printJson(await client.getSpeakerSegments({ identity_id: sid, days, limit, offset: Number(f.offset) }));
+                    return printJson({ error: `Speaker "${identity}" not found` });
+                }
+                await runHandler("search_quotes", params);
+                return;
+            }
+            // Discourse search (name + topic)
+            if (topic) {
+                const params = { speaker_name: identity, topic, days, limit };
+                if (json)
+                    return printJson(await client.searchQuotes({ topic, speaker_name: identity, limit }));
+                await runHandler("search_quotes", params);
+                return;
+            }
+            // Name search, auto-escalate on single match
+            if (json) {
+                const results = await client.searchSpeakers(identity, limit);
+                if (Array.isArray(results) && results.length === 1) {
+                    const sid = results[0].identity_id ?? results[0].id;
+                    if (sid)
+                        return printJson(await client.getSpeaker(Number(sid)));
+                }
+                return printJson(results);
+            }
+            const result = await HANDLERS.find_speakers({ query: identity, limit });
+            print(result.content[0]?.text ?? "");
+        },
+    },
+    channel: {
+        tool: "get_channel",
+        description: "Channel profile",
+        specs: [FLAG_JSON],
+        run: async (args, json) => {
+            const [id] = args.positionals;
+            if (!id) {
+                print("Error: channel ID or name required.");
+                process.exit(1);
+            }
+            const isId = /^\d+$/.test(id);
+            if (json)
+                return printJson(isId ? await client.getChannel(Number(id)) : await client.getChannelByName(id));
+            await runHandler("get_channel", isId ? { channel_id: Number(id) } : { channel_name: id });
+        },
+    },
+    episode: {
+        tool: "get_episode",
+        description: "Episode details or transcript",
+        specs: [{ name: "transcript", type: "boolean" }, FLAG_JSON],
+        run: async (args, json) => {
+            const [id] = args.positionals;
+            if (!id) {
+                print("Error: content ID required.");
+                process.exit(1);
+            }
+            if (json) {
+                const data = await client.getEpisode(id);
+                if (args.flags.transcript)
+                    data.transcript = await client.getTranscript(id);
+                return printJson(data);
+            }
+            await runHandler("get_episode", { content_id: id, include_transcript: args.flags.transcript });
+        },
+    },
+    segment: {
+        tool: "get_segment",
+        description: "Segment detail with audio clip URL",
+        specs: [FLAG_JSON],
+        run: async (args, json) => {
+            const [id] = args.positionals;
+            if (!id) {
+                print("Error: segment ID required.");
+                process.exit(1);
+            }
+            if (json)
+                return printJson(await client.getSegment(Number(id)));
+            await runHandler("get_segment", { segment_id: Number(id) });
+        },
+    },
+    thread: {
+        tool: "get_thread",
+        description: "Conversation context around a quote",
+        specs: [{ name: "n", type: "number", default: 5 }, FLAG_JSON],
+        run: async (args, json) => {
+            const [id] = args.positionals;
+            if (!id) {
+                print("Error: segment ID required.");
+                process.exit(1);
+            }
+            const n = Number(args.flags.n) || 5;
+            if (json)
+                return printJson(await client.getSegmentThread(Number(id), n));
+            await runHandler("get_thread", { segment_id: Number(id), n });
+        },
+    },
+    analyze: {
+        tool: "analyze_topic",
+        description: "AI-powered topic analysis",
+        specs: [FLAG_SPEAKER, FLAG_CHANNEL, FLAG_DAYS,
+            { name: "workflow", alias: "w", type: "string", default: "simple_rag" },
+            FLAG_SKIP_CACHE, FLAG_JSON],
+        run: async (args, json) => {
+            const [query] = args.positionals;
+            if (!query) {
+                print("Error: query is required.");
+                process.exit(1);
+            }
+            const f = args.flags;
+            process.stderr.write("Analyzing... (this may take up to 60 seconds)\n");
+            const params = {
+                query, workflow: f.workflow,
+                speaker_name: f.speaker || undefined,
+                channel: f.channel || undefined,
+                days: Number(f.days) || undefined,
+                skip_cache: f["skip-cache"],
+            };
+            if (json)
+                return printJson(await client.analyze(params));
+            await runHandler("analyze_topic", params);
+        },
+    },
+    compare: {
+        tool: "compare_speakers",
+        description: "Compare speakers on a topic",
+        specs: [{ name: "speakers", type: "string" }, FLAG_DAYS, FLAG_SKIP_CACHE, FLAG_JSON],
+        run: async (args, json) => {
+            const [topic] = args.positionals;
+            if (!topic) {
+                print("Error: topic is required.");
+                process.exit(1);
+            }
+            const f = args.flags;
+            const speakers = (f.speakers || "").split(",").map((s) => s.trim()).filter(Boolean);
+            if (speakers.length < 2) {
+                print("Error: --speakers requires 2-5 comma-separated names.");
+                process.exit(1);
+            }
+            process.stderr.write("Comparing speakers... (this may take up to 60 seconds)\n");
+            const params = {
+                topic, speakers, days: Number(f.days) || 90, skip_cache: f["skip-cache"],
+            };
+            if (json)
+                return printJson(await client.analyze({ query: topic, workflow: "speaker_compare", speaker_names: speakers, days: params.days, skip_cache: params.skip_cache }));
+            await runHandler("compare_speakers", params);
+        },
+    },
+    dossier: {
+        tool: "build_dossier",
+        description: "Comprehensive speaker briefing on a topic",
+        specs: [FLAG_SPEAKER, FLAG_DAYS, FLAG_SKIP_CACHE, FLAG_JSON],
+        run: async (args, json) => {
+            const [topic] = args.positionals;
+            if (!topic) {
+                print("Error: topic is required.");
+                process.exit(1);
+            }
+            const speaker = args.flags.speaker;
+            if (!speaker) {
+                print("Error: --speaker is required.");
+                process.exit(1);
+            }
+            process.stderr.write("Building dossier... (this may take up to 60 seconds)\n");
+            const params = {
+                topic, speaker_name: speaker, days: Number(args.flags.days) || 180, skip_cache: args.flags["skip-cache"],
+            };
+            if (json)
+                return printJson(await client.analyze({ query: topic, workflow: "speaker_dossier", speaker_name: speaker, days: params.days, skip_cache: params.skip_cache }));
+            await runHandler("build_dossier", params);
+        },
+    },
+    contradictions: {
+        tool: "check_contradictions",
+        description: "Find contradictory statements from a speaker",
+        specs: [FLAG_SPEAKER, FLAG_DAYS, FLAG_SKIP_CACHE, FLAG_JSON],
+        run: async (args, json) => {
+            const [topic] = args.positionals;
+            if (!topic) {
+                print("Error: topic is required.");
+                process.exit(1);
+            }
+            const speaker = args.flags.speaker;
+            if (!speaker) {
+                print("Error: --speaker is required.");
+                process.exit(1);
+            }
+            process.stderr.write("Checking contradictions...\n");
+            const params = {
+                topic, speaker_name: speaker, days: Number(args.flags.days) || 365, skip_cache: args.flags["skip-cache"],
+            };
+            if (json)
+                return printJson(await client.analyze({ query: topic, workflow: "contradiction_check", speaker_name: speaker, days: params.days, skip_cache: params.skip_cache }));
+            await runHandler("check_contradictions", params);
+        },
+    },
+    briefing: {
+        tool: "get_briefing",
+        description: "AI discourse briefing",
+        specs: [FLAG_DAYS, { name: "max-topics", type: "number", default: 8 }, FLAG_JSON],
+        run: async (args, json) => {
+            const f = args.flags;
+            const params = { days: Number(f.days) || 3, max_topics: Number(f["max-topics"]) || 8 };
+            if (json)
+                return printJson(await client.getDiscourseSummary(params));
+            await runHandler("get_briefing", params);
+        },
+    },
+    stats: {
+        tool: "get_platform_stats",
+        description: "Platform statistics",
+        specs: [FLAG_DAYS, { name: "projects", type: "boolean" }, FLAG_JSON],
+        run: async (args, json) => {
+            const f = args.flags;
+            if (f.projects) {
+                if (json)
+                    return printJson(await client.getProjectStats());
+                await runHandler("get_project_stats", {});
+            }
+            else {
+                const days = Number(f.days) || 30;
+                if (json)
+                    return printJson(await client.getReportStats(days));
+                await runHandler("get_platform_stats", { days });
+            }
+        },
+    },
+    "top-channels": {
+        tool: "get_top_channels",
+        description: "Top channels by episode count",
+        specs: [FLAG_DAYS, FLAG_LIMIT, FLAG_LANGUAGE, FLAG_JSON],
+        run: async (args, json) => {
+            const f = args.flags;
+            const params = { days: Number(f.days) || 30, limit: Number(f.limit) || 15, language: f.language || undefined };
+            if (json)
+                return printJson(await client.getTopChannels(params));
+            await runHandler("get_top_channels", params);
+        },
+    },
+    "top-speakers": {
+        tool: "get_top_speakers",
+        description: "Top speakers by appearances, talk time, or clips",
+        specs: [FLAG_DAYS, FLAG_LIMIT, { name: "ranking", alias: "r", type: "string", default: "appearances" }, FLAG_JSON],
+        run: async (args, json) => {
+            const f = args.flags;
+            const params = { days: Number(f.days) || 30, limit: Number(f.limit) || 15, ranking: f.ranking };
+            if (json)
+                return printJson(await client.getTopSpeakers(params));
+            await runHandler("get_top_speakers", params);
+        },
+    },
+    network: {
+        tool: "get_speaker_network",
+        description: "Speaker co-appearance network",
+        specs: [FLAG_DAYS, FLAG_LIMIT, FLAG_LANGUAGE, FLAG_JSON],
+        run: async (args, json) => {
+            const f = args.flags;
+            const params = { days: Number(f.days) || 30, limit: Number(f.limit) || 20, language: f.language || "en" };
+            if (json)
+                return printJson(await client.getSpeakerNetwork(params));
+            await runHandler("get_speaker_network", params);
+        },
+    },
+    topics: {
+        tool: "get_topics",
+        description: "Trending topic clusters",
+        specs: [FLAG_LANGUAGE, FLAG_LIMIT, { name: "category", alias: "c", type: "string" },
+            { name: "min-segments", type: "number", default: 50 }, FLAG_JSON],
+        run: async (args, json) => {
+            const f = args.flags;
+            const params = {
+                language: f.language || "en", limit: Number(f.limit) || 20,
+                category: f.category || undefined, min_segments: Number(f["min-segments"]) || 50,
+            };
+            if (json)
+                return printJson(await client.getTopics(params));
+            await runHandler("get_topics", params);
+        },
+    },
+    ads: {
+        tool: "get_ad_analytics",
+        description: "Ad intelligence",
+        specs: [FLAG_DAYS, FLAG_LIMIT, FLAG_OFFSET,
+            { name: "advertisers", type: "boolean" }, { name: "trending", type: "boolean" },
+            { name: "channel", alias: "c", type: "number" },
+            { name: "category", type: "string" }, { name: "sort", type: "string", default: "episodes" },
+            FLAG_JSON],
+        run: async (args, json) => {
+            const [adId] = args.positionals;
+            const f = args.flags;
+            const days = Number(f.days) || 30;
+            if (adId && /^\d+$/.test(adId)) {
+                if (json)
+                    return printJson(await client.getAdvertiser(Number(adId)));
+                await runHandler("get_ad_analytics", { view: "advertiser", advertiser_id: Number(adId), days });
+            }
+            else if (f.advertisers) {
+                if (json)
+                    return printJson(await client.getAdvertisers({ category: f.category || undefined, sort_by: f.sort, limit: Number(f.limit), offset: Number(f.offset) }));
+                await runHandler("get_ad_analytics", { view: "advertisers", category: f.category || undefined, days, limit: Number(f.limit) });
+            }
+            else if (f.trending) {
+                if (json)
+                    return printJson(await client.getAdTrends(days));
+                await runHandler("get_ad_analytics", { view: "trending", days });
+            }
+            else if (Number(f.channel)) {
+                if (json)
+                    return printJson(await client.getAdsByChannel(Number(f.channel), days));
+                await runHandler("get_ad_analytics", { view: "channel", channel_id: Number(f.channel), days });
+            }
+            else {
+                if (json)
+                    return printJson(await client.getAdStats(days));
+                await runHandler("get_ad_analytics", { view: "overview", days });
+            }
+        },
+    },
+    bookmarks: {
+        tool: "manage_bookmarks",
+        description: "Manage bookmarks",
+        specs: [{ name: "type", type: "string" }, { name: "search", type: "string" },
+            FLAG_LIMIT, FLAG_OFFSET, { name: "note", type: "string" }, FLAG_JSON],
+        run: async (args, json) => {
+            const [sub, entityType, entityId] = args.positionals;
+            const f = args.flags;
+            if (sub === "add" && entityType && entityId) {
+                const params = { action: "create", entity_type: entityType, entity_id: entityId, note: f.note || undefined };
+                if (json)
+                    return printJson(await client.createBookmark({ entity_type: entityType, entity_id: entityId, note: f.note || undefined }));
+                await runHandler("manage_bookmarks", params);
+            }
+            else if (sub === "rm" && entityType) {
+                const bookmarkId = Number(entityType);
+                if (json)
+                    return printJson(await client.deleteBookmark(bookmarkId));
+                await runHandler("manage_bookmarks", { action: "delete", bookmark_id: bookmarkId });
+            }
+            else {
+                const params = {
+                    action: "list", entity_type: f.type || undefined,
+                    search: f.search || undefined,
+                    limit: Number(f.limit) || 20, offset: Number(f.offset),
+                };
+                if (json)
+                    return printJson(await client.listBookmarks({
+                        entity_type: f.type || undefined,
+                        search: f.search || undefined,
+                        limit: Number(f.limit), offset: Number(f.offset),
+                    }));
+                await runHandler("manage_bookmarks", params);
+            }
+        },
+    },
+};
+// ---------------------------------------------------------------------------
+// Setup command
+// ---------------------------------------------------------------------------
+async function cmdSetup(force) {
+    const configDir = join(homedir(), ".signal4");
+    const configPath = join(configDir, "config");
+    if (existsSync(configPath) && !force) {
+        print("Config already exists at ~/.signal4/config. Use --force to overwrite.");
+        process.exit(1);
+    }
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    const key = await rl.question("API key: ");
+    rl.close();
+    if (!key.trim()) {
+        print("Error: no API key provided.");
+        process.exit(1);
+    }
+    process.env.SIGNAL4_API_KEY = key.trim();
+    try {
+        const who = await client.whoami();
+        print(`Authenticated as ${who.user_email ?? who.key_prefix ?? "unknown"}`);
+    }
+    catch (err) {
+        print(`Error: invalid API key (${err instanceof Error ? err.message : String(err)})`);
+        process.exit(1);
+    }
+    if (!existsSync(configDir))
+        mkdirSync(configDir, { recursive: true });
+    writeFileSync(configPath, `api_key=${key.trim()}\n`, { mode: 0o600 });
+    try {
+        chmodSync(configPath, 0o600);
+    }
+    catch { /* Windows */ }
+    print(`Saved to ${configPath}`);
+}
+// ---------------------------------------------------------------------------
+// Whoami command
+// ---------------------------------------------------------------------------
+async function cmdWhoami(json) {
+    const data = await client.whoami();
+    if (json)
+        return printJson(data);
+    const lines = [];
+    if (data.key_prefix)
+        lines.push(`Key: ${data.key_prefix}...`);
+    if (data.user_email)
+        lines.push(`Email: ${data.user_email}`);
+    if (data.allowed_projects?.length)
+        lines.push(`Projects: ${data.allowed_projects.join(", ")}`);
+    if (data.scopes?.length)
+        lines.push(`Scopes: ${data.scopes.join(", ")}`);
+    if (data.full_access)
+        lines.push("Access: full");
+    if (data.available_commands?.length)
+        lines.push(`Commands: ${data.available_commands.join(", ")}`);
+    print(lines.join("\n"));
+}
+// ---------------------------------------------------------------------------
+// Help
+// ---------------------------------------------------------------------------
+function showHelp() {
+    const lines = [
+        "Signal4 — media intelligence CLI & MCP server",
+        "",
+        "Usage: s4 <command> [args] [flags]",
+        "       s4 --mcp          Start MCP server (stdio transport)",
+        "",
+        "Search:",
+        '  s4 search "immigration" --speaker "Trudeau" --days 7',
+        '  s4 claims "AI regulation" --entity "OpenAI"',
+        '  s4 trend "tariffs" --recent 7 --baseline 30',
+        "",
+        "Explore:",
+        '  s4 speaker "Tucker Carlson"',
+        '  s4 speaker "Tucker Carlson" "economy"        # discourse',
+        '  s4 channel "Power & Politics"',
+        "  s4 episode pod_8f1e55513f70 --transcript",
+        "  s4 segment 28553756",
+        "  s4 thread 28553756 --n 10",
+        "",
+        "Analyze:",
+        '  s4 analyze "carbon tax" --days 14',
+        '  s4 compare "tariffs" --speakers "Trump,Biden"',
+        '  s4 dossier "immigration" --speaker "Carlson"',
+        '  s4 contradictions "vaccines" --speaker "Trump"',
+        "  s4 briefing --days 7",
+        "",
+        "Reports:",
+        "  s4 stats --days 30",
+        "  s4 top-speakers --ranking talkative",
+        "  s4 top-channels --limit 25",
+        "  s4 network",
+        "  s4 topics --category economy",
+        "  s4 ads --trending",
+        "",
+        "Data:",
+        "  s4 bookmarks",
+        "  s4 bookmarks add segment 12345 --note 'key quote'",
+        "  s4 bookmarks rm 7",
+        "",
+        "Account:",
+        "  s4 setup                Save API key",
+        "  s4 whoami               Show key info",
+        "",
+        "Flags:",
+        "  --json                  Raw JSON output",
+        "  --help, -h              Show this help",
+        "",
+        "MCP server:",
+        "  s4 mcp                  Start MCP server for Claude Desktop / Cursor",
+    ];
+    print(lines.join("\n"));
+}
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+export async function main() {
+    applyConfig();
+    const argv = process.argv.slice(2);
+    // Help
+    if (!argv.length || argv.includes("--help") || argv.includes("-h")) {
+        showHelp();
+        process.exit(0);
+    }
+    // MCP mode
+    if (argv[0] === "mcp" || argv.includes("--mcp")) {
+        await import("./index.js");
+        return;
+    }
+    const command = argv[0];
+    const rest = argv.slice(1);
+    // Setup (no API key needed)
+    if (command === "setup") {
+        await cmdSetup(rest.includes("--force"));
+        return;
+    }
+    // Check API key
+    if (!process.env.SIGNAL4_API_KEY) {
+        process.stderr.write("No API key configured. Run `s4 setup` or set SIGNAL4_API_KEY.\n");
+        process.exit(1);
+    }
+    // Whoami
+    if (command === "whoami") {
+        await cmdWhoami(rest.includes("--json"));
+        return;
+    }
+    // Lookup command
+    const cmd = COMMANDS[command];
+    if (!cmd) {
+        process.stderr.write(`Unknown command: ${command}\n\nRun s4 --help for usage.\n`);
+        process.exit(1);
+    }
+    // Parse args
+    const args = parseArgs(rest, cmd.specs);
+    const json = args.flags.json;
+    try {
+        await cmd.run(args, json);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`Error: ${msg}\n`);
+        process.exit(1);
+    }
+}
+main().catch((err) => {
+    process.stderr.write(`Fatal: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map