@vaultgradient/pipequery-cli 0.4.0 → 0.6.1

package/dist/index.js

@@ -2,7 +2,7 @@
 
 // src/index.ts
 import { Command } from "commander";
-import chalk8 from "chalk";
+import chalk9 from "chalk";
 
 // src/commands/init.ts
 import { writeFile } from "fs/promises";
@@ -123,7 +123,8 @@ async function loadConfig(cwd = process.cwd()) {
     remote: raw.remote,
     sources: raw.sources ?? {},
     endpoints: raw.endpoints ?? {},
-    dashboards: raw.dashboards ?? {}
+    dashboards: raw.dashboards ?? {},
+    watches: raw.watches ?? {}
   };
   return { config, path: configPath };
 }
@@ -942,19 +943,8 @@ var SourceManager = class {
   }
 };
 
-// src/server/routes/health.ts
-function registerHealthRoutes(app, sourceManager, startedAt) {
-  app.get("/health", async () => {
-    return { status: "ok", uptime: Date.now() - startedAt.getTime() };
-  });
-  app.get("/status", async () => {
-    return {
-      status: "ok",
-      uptime: Date.now() - startedAt.getTime(),
-      sources: sourceManager.getAllStatuses()
-    };
-  });
-}
+// src/server/watches/manager.ts
+import { createHash } from "crypto";
 
 // ../src/engine/types.ts
 var AGGREGATE_NAMES = /* @__PURE__ */ new Set([
@@ -2782,6 +2772,333 @@ function query(context, expression) {
   return fn(context);
 }
 
+// src/server/activity-log.ts
+var MAX_ENTRIES = 100;
+var entries = [];
+function logActivity(level, message) {
+  entries.push({
+    time: (/* @__PURE__ */ new Date()).toISOString(),
+    level,
+    message
+  });
+  if (entries.length > MAX_ENTRIES) {
+    entries.splice(0, entries.length - MAX_ENTRIES);
+  }
+}
+function getActivityLog(since) {
+  if (!since) return [...entries];
+  return entries.filter((e) => e.time > since);
+}
+function info(msg) {
+  logActivity("info", msg);
+}
+function warn(msg) {
+  logActivity("warn", msg);
+}
+function error(msg) {
+  logActivity("error", msg);
+}
+
+// src/telegram/notifier.ts
+import { Bot } from "grammy";
+
+// src/telegram/format.ts
+var TELEGRAM_TEXT_LIMIT = 4096;
+var FENCE_OVERHEAD = 32;
+var TRUNCATE_BUDGET = TELEGRAM_TEXT_LIMIT - FENCE_OVERHEAD;
+var MAX_ROWS_INLINE = 30;
+var MAX_COL_WIDTH = 24;
+function formatResult(result, opts = {}) {
+  const maxRows = opts.maxRows ?? MAX_ROWS_INLINE;
+  if (Array.isArray(result)) {
+    if (result.length === 0) return "<i>(no rows)</i>";
+    const allObjects = result.every(
+      (r) => r !== null && typeof r === "object" && !Array.isArray(r)
+    );
+    if (allObjects) {
+      return renderTable(result, result.length, maxRows, opts);
+    }
+    return renderJson(result.slice(0, maxRows), result.length, maxRows);
+  }
+  return renderJson(result, 1, 1);
+}
+function formatError(err) {
+  const msg = err instanceof Error ? err.message : String(err);
+  return `\u274C <b>Error</b>
+<pre>${escapeHtml(msg)}</pre>`;
+}
+function renderTable(rows, totalCount, maxRows, opts) {
+  const maxColWidth = opts.maxColWidth ?? MAX_COL_WIDTH;
+  const sample = rows.slice(0, maxRows);
+  const columns = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const r of sample) {
+    for (const k of Object.keys(r)) {
+      if (!seen.has(k)) {
+        seen.add(k);
+        columns.push(k);
+      }
+    }
+  }
+  const widths = columns.map(
+    (c) => Math.min(
+      maxColWidth,
+      Math.max(c.length, ...sample.map((r) => stringifyCell(r[c]).length))
+    )
+  );
+  const headerRow = columns.map((c, i) => padCell(c, widths[i])).join("  ");
+  const sep = widths.map((w) => "\u2500".repeat(w)).join("  ");
+  const dataRows = sample.map(
+    (r) => columns.map((c, i) => padCell(stringifyCell(r[c]), widths[i])).join("  ")
+  );
+  const lines = [headerRow, sep, ...dataRows];
+  let body = lines.join("\n");
+  if (body.length > TRUNCATE_BUDGET) {
+    body = body.slice(0, TRUNCATE_BUDGET - 30) + "\n... (truncated)";
+  }
+  let out = `<pre>${escapeHtml(body)}</pre>`;
+  if (totalCount > maxRows) {
+    out += `
+<i>showing ${maxRows} of ${totalCount} rows \u2014 narrow your query</i>`;
+  } else {
+    out += `
+<i>${totalCount} row${totalCount === 1 ? "" : "s"}</i>`;
+  }
+  return out;
+}
+function stringifyCell(value) {
+  if (value === null || value === void 0) return "";
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  return JSON.stringify(value);
+}
+function padCell(s, width) {
+  if (s.length > width) return s.slice(0, width - 1) + "\u2026";
+  return s.padEnd(width, " ");
+}
+function renderJson(data, totalCount, maxRows) {
+  const text = JSON.stringify(data, null, 2);
+  let body = text;
+  if (body.length > TRUNCATE_BUDGET) {
+    body = body.slice(0, TRUNCATE_BUDGET - 30) + "\n... (truncated)";
+  }
+  let out = `<pre>${escapeHtml(body)}</pre>`;
+  if (Array.isArray(data) && totalCount > maxRows) {
+    out += `
+<i>showing ${maxRows} of ${totalCount} rows \u2014 narrow your query</i>`;
+  }
+  return out;
+}
+var HTML_ENTITIES = {
+  "&": "&amp;",
+  "<": "&lt;",
+  ">": "&gt;"
+};
+function escapeHtml(s) {
+  return s.replace(/[&<>]/g, (c) => HTML_ENTITIES[c] ?? c);
+}
+
+// src/telegram/notifier.ts
+var botCache = /* @__PURE__ */ new Map();
+function expandEnv4(input) {
+  return input.replace(/\$\{([A-Z0-9_]+)\}/gi, (_, name) => process.env[name] ?? "");
+}
+function getBot(token) {
+  let bot = botCache.get(token);
+  if (!bot) {
+    bot = new Bot(token);
+    botCache.set(token, bot);
+  }
+  return bot;
+}
+var TelegramNotifier = class {
+  token;
+  chatId;
+  template;
+  constructor(cfg) {
+    const tokenSource = cfg.botToken ?? process.env.PIPEQUERY_TG_BOT_TOKEN;
+    if (!tokenSource) {
+      throw new Error(
+        "TelegramNotifier: no bot token. Set notify.telegram.botToken or PIPEQUERY_TG_BOT_TOKEN."
+      );
+    }
+    this.token = expandEnv4(tokenSource);
+    this.chatId = cfg.chatId;
+    this.template = cfg.message;
+  }
+  async notify(payload) {
+    const bot = getBot(this.token);
+    const text = this.renderMessage(payload);
+    await bot.api.sendMessage(this.chatId, text, {
+      parse_mode: "HTML",
+      link_preview_options: { is_disabled: true }
+    });
+  }
+  renderMessage(payload) {
+    if (this.template) {
+      return renderTemplate(this.template, payload);
+    }
+    const header = `\u{1F514} <b>Watch fired:</b> <code>${escapeHtml(payload.watchName)}</code>`;
+    const reason = `<i>${escapeHtml(payload.reason)}</i>`;
+    const body = formatResult(payload.result);
+    return [header, reason, body].join("\n");
+  }
+};
+function renderTemplate(tmpl, payload) {
+  const result = payload.result;
+  const rows = Array.isArray(result) ? result : [result];
+  const firstRow = rows[0];
+  const count = rows.length;
+  return tmpl.replace(/\{\{\s*\.([a-zA-Z0-9_]+)\s*\}\}/g, (match, name) => {
+    if (name === "count") return String(count);
+    if (name === "watchName") return payload.watchName;
+    if (name === "reason") return payload.reason;
+    if (firstRow && typeof firstRow === "object" && firstRow !== null) {
+      const value = firstRow[name];
+      if (value === void 0) return match;
+      return String(value);
+    }
+    return match;
+  });
+}
+
+// src/server/watches/manager.ts
+var DEFAULT_INTERVAL_MS4 = 6e4;
+var WatchManager = class {
+  constructor(sourceManager) {
+    this.sourceManager = sourceManager;
+  }
+  sourceManager;
+  watches = /* @__PURE__ */ new Map();
+  disposed = false;
+  start(configs) {
+    for (const [name, cfg] of Object.entries(configs)) {
+      try {
+        this.startOne(name, cfg);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        error(`Watch "${name}" failed to start: ${msg}`);
+        process.stderr.write(`[pipequery-watch] "${name}" failed to start: ${msg}
+`);
+      }
+    }
+  }
+  startOne(name, cfg) {
+    const notifiers = buildNotifiers(cfg.notify);
+    if (notifiers.length === 0) {
+      throw new Error(`watch has no notification channels configured`);
+    }
+    const intervalMs = cfg.interval ? parseDuration(cfg.interval) : DEFAULT_INTERVAL_MS4;
+    const state = {
+      config: cfg,
+      notifiers,
+      intervalMs,
+      timer: null,
+      lastWasEmpty: null,
+      lastHash: null
+    };
+    this.watches.set(name, state);
+    info(`Watch "${name}" registered (every ${cfg.interval ?? "60s"})`);
+    void this.tick(name);
+    state.timer = setInterval(() => void this.tick(name), intervalMs);
+  }
+  async tick(name) {
+    if (this.disposed) return;
+    const state = this.watches.get(name);
+    if (!state) return;
+    let result;
+    try {
+      const ctx = this.sourceManager.getContext();
+      result = query(ctx, state.config.query);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      error(`Watch "${name}" query failed: ${msg}`);
+      return;
+    }
+    const fireWhen = state.config.fireWhen ?? "when_non_empty";
+    const isEmpty = isResultEmpty(result);
+    const hash = hashResult(result);
+    let shouldFire = false;
+    let reason = "";
+    if (fireWhen === "when_non_empty") {
+      if (state.lastWasEmpty !== false && !isEmpty) {
+        shouldFire = true;
+        reason = "result transitioned to non-empty";
+      }
+    } else if (fireWhen === "when_empty") {
+      if (state.lastWasEmpty !== true && isEmpty) {
+        shouldFire = true;
+        reason = "result transitioned to empty";
+      }
+    } else if (fireWhen === "on_change") {
+      if (state.lastHash !== null && state.lastHash !== hash) {
+        shouldFire = true;
+        reason = "result content changed";
+      }
+    }
+    state.lastWasEmpty = isEmpty;
+    state.lastHash = hash;
+    if (!shouldFire) return;
+    info(`Watch "${name}" fired (${reason})`);
+    await Promise.all(
+      state.notifiers.map(
+        (n) => n.notify({ watchName: name, result, reason }).catch((err) => {
+          const msg = err instanceof Error ? err.message : String(err);
+          error(`Watch "${name}" notify failed: ${msg}`);
+          process.stderr.write(`[pipequery-watch] "${name}" notify failed: ${msg}
+`);
+        })
+      )
+    );
+  }
+  stop(name) {
+    const state = this.watches.get(name);
+    if (!state) return false;
+    if (state.timer) clearInterval(state.timer);
+    this.watches.delete(name);
+    return true;
+  }
+  list() {
+    return [...this.watches.keys()];
+  }
+  dispose() {
+    this.disposed = true;
+    for (const state of this.watches.values()) {
+      if (state.timer) clearInterval(state.timer);
+    }
+    this.watches.clear();
+  }
+};
+function buildNotifiers(notify) {
+  const out = [];
+  if (notify.telegram) out.push(new TelegramNotifier(notify.telegram));
+  return out;
+}
+function isResultEmpty(result) {
+  if (result === null || result === void 0) return true;
+  if (Array.isArray(result)) return result.length === 0;
+  if (typeof result === "object") return Object.keys(result).length === 0;
+  return false;
+}
+function hashResult(result) {
+  const json = JSON.stringify(result, (_, v) => v === void 0 ? null : v);
+  return createHash("sha256").update(json).digest("hex");
+}
+
+// src/server/routes/health.ts
+function registerHealthRoutes(app, sourceManager, startedAt) {
+  app.get("/health", async () => {
+    return { status: "ok", uptime: Date.now() - startedAt.getTime() };
+  });
+  app.get("/status", async () => {
+    return {
+      status: "ok",
+      uptime: Date.now() - startedAt.getTime(),
+      sources: sourceManager.getAllStatuses()
+    };
+  });
+}
+
 // src/server/routes/control.ts
 function registerControlRoutes(app, sourceManager, endpointRegistry, configCallbacks) {
   app.get("/api/_control/sources", async () => {
@@ -2969,33 +3286,6 @@ function sendAllPanels(res, queries, sourceManager) {
   }
 }
 
-// src/server/activity-log.ts
-var MAX_ENTRIES = 100;
-var entries = [];
-function logActivity(level, message) {
-  entries.push({
-    time: (/* @__PURE__ */ new Date()).toISOString(),
-    level,
-    message
-  });
-  if (entries.length > MAX_ENTRIES) {
-    entries.splice(0, entries.length - MAX_ENTRIES);
-  }
-}
-function getActivityLog(since) {
-  if (!since) return [...entries];
-  return entries.filter((e) => e.time > since);
-}
-function info(msg) {
-  logActivity("info", msg);
-}
-function warn(msg) {
-  logActivity("warn", msg);
-}
-function error(msg) {
-  logActivity("error", msg);
-}
-
 // src/server/app.ts
 async function createServer(config, configPath, cwd) {
   const app = Fastify({ logger: false });
@@ -3056,8 +3346,12 @@ async function createServer(config, configPath, cwd) {
   registerControlRoutes(app, sourceManager, { endpoints }, configCallbacks);
   registerSSERoutes(app, sourceManager);
   registerDynamicRoutes(app, sourceManager, endpoints);
+  const watchManager = new WatchManager(sourceManager);
+  if (config.watches && Object.keys(config.watches).length > 0) {
+    watchManager.start(config.watches);
+  }
   info("Server ready");
-  return { app, sourceManager, endpoints };
+  return { app, sourceManager, endpoints, watchManager };
 }
 
 // src/utils/banner.ts
@@ -3262,14 +3556,14 @@ async function queryCommand(expression, opts) {
     return;
   }
   if (Array.isArray(result) && result.length > 0 && typeof result[0] === "object") {
-    renderTable(result);
+    renderTable2(result);
   } else if (typeof result === "object" && result !== null && !Array.isArray(result)) {
-    renderTable([result]);
+    renderTable2([result]);
   } else {
     console.log(result);
   }
 }
-function renderTable(rows) {
+function renderTable2(rows) {
   if (rows.length === 0) {
     log.dim("(empty result)");
     return;
@@ -5170,6 +5464,579 @@ async function buildProvider(attachUrl) {
   return new LocalProvider(config, cwd);
 }
 
+// src/telegram/bot.ts
+import { Bot as Bot2, GrammyError, HttpError } from "grammy";
+function buildBot(token, provider, opts = {}) {
+  const bot = new Bot2(token);
+  const allowList = normalizeAllowList(opts.allowUsers ?? []);
+  const nl = opts.nl;
+  bot.use(async (ctx, next) => {
+    if (allowList.size === 0) {
+      const id = ctx.from?.id;
+      if (id) trackUnauthSeen(id, ctx.from?.username);
+      await next();
+      return;
+    }
+    if (!isAllowed(ctx, allowList)) {
+      await ctx.reply("\u{1F512} You are not authorized to use this bot.");
+      return;
+    }
+    await next();
+  });
+  bot.command("start", async (ctx) => {
+    await ctx.reply(
+      [
+        "\u{1F44B} <b>pipequery bot</b>",
+        "",
+        "Run pipequery expressions against your configured data sources from chat.",
+        "",
+        "<b>Commands</b>",
+        "/sources \u2014 list configured sources and their health",
+        "/describe &lt;name&gt; \u2014 sample rows + field names",
+        "/endpoints \u2014 list pre-configured endpoints",
+        "/call &lt;path&gt; \u2014 execute a pre-configured endpoint",
+        "/query &lt;expression&gt; \u2014 run an arbitrary pipequery expression",
+        "/help \u2014 this message"
+      ].join("\n"),
+      { parse_mode: "HTML" }
+    );
+  });
+  bot.command("help", async (ctx) => {
+    const lines = [
+      "<b>Examples</b>",
+      "<code>/sources</code>",
+      "<code>/describe products</code>",
+      "<code>/query products | sort(price desc) | first(5)</code>",
+      "<code>/query crypto | where(price &gt; 100) | rollup(avg(price) as avg)</code>",
+      "<code>/call /api/top-coins</code>"
+    ];
+    if (nl) {
+      lines.push(
+        "",
+        "<b>Natural language</b>",
+        "Send any plain-text message (no leading <code>/</code>) and I'll translate it into a pipequery expression and run it.",
+        'Example: <i>"top 5 most expensive paid orders"</i>'
+      );
+    }
+    lines.push(
+      "",
+      "<b>Tips</b>",
+      "\u2022 Wrap quoted strings carefully \u2014 Telegram's autocorrect can mangle them. Send long expressions as a separate message.",
+      "\u2022 Use <code>/describe &lt;source&gt;</code> to discover field names before constructing a where clause.",
+      "\u2022 Results &gt; 30 rows are truncated with a footer; tighten your query to see all of them."
+    );
+    await ctx.reply(lines.join("\n"), { parse_mode: "HTML" });
+  });
+  bot.command("sources", async (ctx) => {
+    try {
+      const sources = await provider.listSources();
+      if (sources.length === 0) {
+        await ctx.reply("<i>No sources configured.</i>", { parse_mode: "HTML" });
+        return;
+      }
+      const lines = sources.map((s) => {
+        const dot = s.status.healthy ? "\u{1F7E2}" : "\u{1F534}";
+        const rowCount = s.status.rowCount.toLocaleString();
+        const err = s.status.error ? ` <i>(${escapeHtml(s.status.error)})</i>` : "";
+        return `${dot} <b>${escapeHtml(s.name)}</b> \u2014 ${rowCount} rows${err}`;
+      });
+      await ctx.reply(lines.join("\n"), { parse_mode: "HTML" });
+    } catch (err) {
+      await ctx.reply(formatError(err), { parse_mode: "HTML" });
+    }
+  });
+  bot.command("describe", async (ctx) => {
+    const name = ctx.match.trim();
+    if (!name) {
+      await ctx.reply("Usage: <code>/describe &lt;source-name&gt;</code>", { parse_mode: "HTML" });
+      return;
+    }
+    try {
+      const desc = await provider.describeSource(name, 5);
+      if (!desc) {
+        await ctx.reply(`Source <code>${escapeHtml(name)}</code> not found.`, { parse_mode: "HTML" });
+        return;
+      }
+      const fields = desc.fields.length ? desc.fields.map((f) => `<code>${escapeHtml(f)}</code>`).join(", ") : "<i>(none inferred)</i>";
+      const sample = formatResult(desc.sample);
+      await ctx.reply(
+        `<b>${escapeHtml(name)}</b> \u2014 ${desc.status.rowCount.toLocaleString()} rows
+<b>Fields:</b> ${fields}
+
+<b>Sample:</b>
+${sample}`,
+        { parse_mode: "HTML" }
+      );
+    } catch (err) {
+      await ctx.reply(formatError(err), { parse_mode: "HTML" });
+    }
+  });
+  bot.command("endpoints", async (ctx) => {
+    try {
+      const endpoints = await provider.listEndpoints();
+      if (endpoints.length === 0) {
+        await ctx.reply("<i>No endpoints configured.</i>", { parse_mode: "HTML" });
+        return;
+      }
+      const lines = endpoints.map(
+        (e) => `<b>${escapeHtml(e.path)}</b>
+<code>${escapeHtml(e.config.query)}</code>`
+      );
+      await ctx.reply(lines.join("\n\n"), { parse_mode: "HTML" });
+    } catch (err) {
+      await ctx.reply(formatError(err), { parse_mode: "HTML" });
+    }
+  });
+  bot.command("call", async (ctx) => {
+    const path = ctx.match.trim();
+    if (!path) {
+      await ctx.reply("Usage: <code>/call &lt;endpoint-path&gt;</code>", { parse_mode: "HTML" });
+      return;
+    }
+    try {
+      const result = await provider.callEndpoint(path);
+      await ctx.reply(formatResult(result), { parse_mode: "HTML" });
+    } catch (err) {
+      await ctx.reply(formatError(err), { parse_mode: "HTML" });
+    }
+  });
+  bot.command("query", async (ctx) => {
+    const expr = ctx.match.trim();
+    if (!expr) {
+      await ctx.reply("Usage: <code>/query &lt;pipequery expression&gt;</code>", { parse_mode: "HTML" });
+      return;
+    }
+    try {
+      const result = await provider.runQuery(expr);
+      await ctx.reply(formatResult(result), { parse_mode: "HTML" });
+    } catch (err) {
+      await ctx.reply(formatError(err), { parse_mode: "HTML" });
+    }
+  });
+  bot.on("message:text", async (ctx) => {
+    const text = ctx.message.text.trim();
+    if (!text || text.startsWith("/")) return;
+    if (!nl) {
+      await ctx.reply(
+        "I don't recognise that. Use <code>/help</code> to see the available commands. Natural-language queries are disabled \u2014 start the bot with <code>--anthropic-key</code> to enable them.",
+        { parse_mode: "HTML" }
+      );
+      return;
+    }
+    try {
+      await ctx.replyWithChatAction("typing");
+      const { expression, explanation } = await nl.translate(text);
+      if (!expression) {
+        const reason = explanation || "I couldn't translate that into a pipequery expression.";
+        await ctx.reply(`\u{1F914} ${escapeHtml(reason)}`, { parse_mode: "HTML" });
+        return;
+      }
+      const result = await provider.runQuery(expression);
+      const header = `<i>${escapeHtml(explanation || "Translated query")}</i>
+<code>${escapeHtml(expression)}</code>
+
+`;
+      await ctx.reply(header + formatResult(result), { parse_mode: "HTML" });
+    } catch (err) {
+      await ctx.reply(formatError(err), { parse_mode: "HTML" });
+    }
+  });
+  bot.catch((err) => {
+    if (err.error instanceof GrammyError) {
+      process.stderr.write(`[pipequery-telegram] grammy error: ${err.error.description}
+`);
+    } else if (err.error instanceof HttpError) {
+      process.stderr.write(`[pipequery-telegram] http error: ${err.error.message}
+`);
+    } else {
+      process.stderr.write(`[pipequery-telegram] unhandled: ${err.error}
+`);
+    }
+  });
+  return bot;
+}
+function normalizeAllowList(entries2) {
+  const set = /* @__PURE__ */ new Set();
+  for (const raw of entries2) {
+    const trimmed = raw.trim().replace(/^@/, "").toLowerCase();
+    if (trimmed) set.add(trimmed);
+  }
+  return set;
+}
+function isAllowed(ctx, allowList) {
+  const from = ctx.from;
+  if (!from) return false;
+  if (allowList.has(String(from.id))) return true;
+  if (from.username && allowList.has(from.username.toLowerCase())) return true;
+  return false;
+}
+var seenUnauth = /* @__PURE__ */ new Set();
+function trackUnauthSeen(id, username) {
+  if (seenUnauth.has(id)) return;
+  seenUnauth.add(id);
+  process.stderr.write(
+    `[pipequery-telegram] WARNING: bot has no allowlist; user "${username ?? id}" can query freely. Restart with --allow-user @yourname to lock it down.
+`
+  );
+}
+
+// src/telegram/nl.ts
+import Anthropic from "@anthropic-ai/sdk";
+var MODEL = "claude-haiku-4-5";
+var MAX_TOKENS = 1024;
+var SCHEMA_TTL_MS = 6e4;
+function createNLTranslator(provider, opts) {
+  const client = opts.client ?? new Anthropic({ apiKey: opts.apiKey });
+  const model = opts.model ?? MODEL;
+  let cachedSchema = null;
+  async function getSchemaPreamble() {
+    const now = Date.now();
+    if (cachedSchema && now - cachedSchema.builtAt < SCHEMA_TTL_MS) {
+      return cachedSchema.text;
+    }
+    const text = await buildSchemaPreamble(provider);
+    cachedSchema = { text, builtAt: now };
+    return text;
+  }
+  async function translate(question) {
+    const schema = await getSchemaPreamble();
+    const response = await client.messages.create({
+      model,
+      max_tokens: MAX_TOKENS,
+      system: [
+        // Cache breakpoint #1 — the always-stable DSL grammar + instructions.
+        // This is the largest block and the one that benefits most from being
+        // cached across every translation request the bot ever serves.
+        {
+          type: "text",
+          text: SYSTEM_PROMPT,
+          cache_control: { type: "ephemeral" }
+        },
+        // Cache breakpoint #2 — the per-tenant source schema. Stable until
+        // the yaml changes (or SCHEMA_TTL_MS elapses).
+        {
+          type: "text",
+          text: schema,
+          cache_control: { type: "ephemeral" }
+        }
+      ],
+      messages: [
+        {
+          role: "user",
+          content: question
+        }
+      ]
+    });
+    const text = extractText(response);
+    return parseTranslation(text);
+  }
+  return {
+    translate,
+    invalidateSchema: () => {
+      cachedSchema = null;
+    }
+  };
+}
+async function buildSchemaPreamble(provider) {
+  const sources = await provider.listSources();
+  const endpoints = await provider.listEndpoints();
+  const sourceLines = [];
+  for (const s of sources) {
+    let fields = [];
+    try {
+      const desc = await provider.describeSource(s.name, 3);
+      if (desc) fields = desc.fields;
+    } catch {
+    }
+    const fieldStr = fields.length ? ` \u2014 fields: ${fields.join(", ")}` : "";
+    sourceLines.push(`- ${s.name} (${s.status.rowCount} rows)${fieldStr}`);
+  }
+  const endpointLines = endpoints.map((e) => `- ${e.path} \u2192 ${e.config.query}`);
+  return [
+    "## Available data sources",
+    sourceLines.length ? sourceLines.join("\n") : "(no sources configured)",
+    "",
+    "## Pre-defined endpoints",
+    endpointLines.length ? endpointLines.join("\n") : "(no endpoints configured)"
+  ].join("\n");
+}
+function extractText(response) {
+  const parts = [];
+  for (const block of response.content) {
+    if (block.type === "text") parts.push(block.text);
+  }
+  return parts.join("").trim();
+}
+function parseTranslation(raw) {
+  const cleaned = raw.replace(/^```json\s*/i, "").replace(/^```\s*/i, "").replace(/```\s*$/i, "").trim();
+  const start = cleaned.indexOf("{");
+  const end = cleaned.lastIndexOf("}");
+  if (start === -1 || end === -1 || end < start) {
+    throw new Error(`Translator returned non-JSON: ${truncate(raw, 200)}`);
+  }
+  const slice = cleaned.slice(start, end + 1);
+  let parsed;
+  try {
+    parsed = JSON.parse(slice);
+  } catch (err) {
+    throw new Error(`Translator returned invalid JSON: ${truncate(raw, 200)}`);
+  }
+  if (typeof parsed !== "object" || parsed === null || typeof parsed.expression !== "string") {
+    throw new Error(`Translator response missing "expression" field: ${truncate(raw, 200)}`);
+  }
+  const obj = parsed;
+  return {
+    expression: obj.expression.trim(),
+    explanation: typeof obj.explanation === "string" ? obj.explanation.trim() : ""
+  };
+}
+function truncate(s, n) {
+  return s.length > n ? `${s.slice(0, n)}\u2026` : s;
+}
+var SYSTEM_PROMPT = `You are a translator that converts natural-language questions into PipeQuery expressions.
+
+PipeQuery is a small, pipe-style query DSL. Every expression starts with a source name (or a literal array) and pipes into one or more operations using \`|\`. PipeQuery is read-only by construction \u2014 there is no DDL, DML, INSERT, UPDATE, DELETE, or DROP. You will never produce SQL.
+
+# Output contract
+
+You MUST respond with a SINGLE JSON object and nothing else. No prose, no markdown, no code fences.
+
+The object has exactly two fields:
+  - "expression": a string containing the PipeQuery expression to execute.
+  - "explanation": a one-sentence plain-English description of what the expression does.
+
+Example:
+{"expression": "orders | where(status == \\"paid\\") | sort(total desc) | first(5)", "explanation": "Top 5 paid orders by total."}
+
+If the user's question cannot be answered with the available sources, return:
+{"expression": "", "explanation": "<brief reason why no expression was produced>"}
+
+# Grammar
+
+Pipeline:
+  <source_name> | <operation> | <operation> | ...
+
+Sources are referenced by their bare name (no quotes). The available source names are listed in the schema preamble that follows this prompt.
+
+# Operations
+
+## where(<expression>)
+Filter rows. The expression is evaluated per row and must return a boolean.
+  - Comparison operators: ==  !=  >  >=  <  <=
+  - Logical operators: &&  ||  !
+  - Arithmetic: +  -  *  /  %
+  - Field reference: bare identifier (e.g., \`price\`, \`status\`)
+  - Strings: double-quoted ("paid")
+  - Numbers: 1, 1.5, -42
+  - Booleans: true, false
+  - Null: null
+
+Examples:
+  events | where(severity == "high")
+  trades | where(price > 100 && symbol == "BTC")
+  users | where(!banned)
+
+## sort(<field> asc|desc, ...)
+Sort by one or more fields. Direction is optional, defaults to asc.
+  orders | sort(total desc)
+  orders | sort(country asc, total desc)
+
+## first(N) / last(N)
+Take the first / last N rows. N must be a positive integer literal.
+  trades | sort(ts desc) | first(10)
+
+## distinct / distinct(field, ...)
+Deduplicate rows. With no args, dedupes on the full row; with args, dedupes on the listed fields.
+  users | distinct(email)
+
+## select(<expression>, ...)
+Project fields. Each expression can be a bare field, a computed expression, or an alias (\`expr as name\`).
+  orders | select(id, total, total * 0.1 as tax)
+
+## groupBy(<field>, ...) and rollup
+Aggregate. \`groupBy\` keeps groups; \`rollup\` collapses each group to one row with computed aggregates.
+
+  orders | rollup(country, sum(total) as revenue, count() as n)
+  trades | groupBy(symbol) | rollup(avg(price) as avg)
+
+Aggregate functions: sum, avg, min, max, count, median, stddev, var, percentile, distinct_count, first_value, last_value, vwap, wavg, pct, sharpe, calmar, sortino, info_ratio, drawdown, sum_abs, abs_sum.
+
+\`count()\` takes no field. \`percentile(field, p)\` and \`vwap(value, weight)\` take two args.
+
+## flatten / flatten(field)
+Unnest array values. With \`flatten(orders)\` each element of \`row.orders\` becomes its own row.
+
+## map(<expression>, ...)
+Transform each row into a new shape (similar to \`select\` but always emits a new object).
+
+## reduce(initial, accumulator)
+Fold rows into a single value. Rare; prefer rollup.
+
+## join(<source>, <condition>)
+Inner join with another source on a boolean condition. Use \`left\` and \`right\` to refer to fields.
+  orders | join(customers, left.customer_id == right.id)
+
+## pivot(<field>, <agg>, ...)
+Pivot rows into columns by a key field.
+
+# Conventions and best practices
+
+1. Prefer \`rollup\` over \`groupBy\` unless the caller wants the per-group rows kept.
+2. Always cap result size with \`first(N)\` for "top N" or "show me" questions; default to 10 if the user doesn't specify.
+3. Use the EXACT field names from the schema preamble. Do not invent fields.
+4. If two sources need to be joined and there's no obvious join key in the schema, prefer to ask for clarification by emitting the empty-expression form rather than guessing.
+5. Quote string literals with double quotes; escape internal double quotes with \\".
+6. Do not produce SQL, JavaScript, or English in the expression field \u2014 only PipeQuery.
+7. Numbers are bare; no thousands separators, no quotes.
+8. Comparisons against null use \`== null\` / \`!= null\`.
+
+# Worked examples
+
+Question: "What are the top 5 most expensive orders that were paid?"
+{"expression": "orders | where(status == \\"paid\\") | sort(total desc) | first(5)", "explanation": "Top 5 paid orders by total."}
+
+Question: "Average BTC price right now"
+{"expression": "trades | where(symbol == \\"BTC\\") | rollup(avg(price) as avg_price)", "explanation": "Average price across all BTC rows."}
+
+Question: "Revenue by country"
+{"expression": "orders | rollup(country, sum(total) as revenue) | sort(revenue desc)", "explanation": "Sum of order totals grouped by country, highest first."}
+
+Question: "How many distinct users placed an order?"
+{"expression": "orders | rollup(distinct_count(user_id) as users)", "explanation": "Count of unique user IDs in orders."}
+
+Question: "Show high-severity events from the last hour"
+(only answerable if the schema has a timestamp field; otherwise return empty.)
+{"expression": "events | where(severity == \\"high\\") | sort(ts desc) | first(50)", "explanation": "Most recent high-severity events, capped at 50."}
+
+Question: "Drop the orders table"
+{"expression": "", "explanation": "PipeQuery is read-only and cannot drop tables."}
+
+Question: "How many rows in foo?"
+(only answerable if a source named \`foo\` exists; otherwise return empty.)
+{"expression": "foo | rollup(count() as n)", "explanation": "Row count of foo."}
+
+# Reminder
+
+- Output exactly ONE JSON object.
+- The "expression" field must be valid PipeQuery referencing only sources from the schema preamble.
+- Use double quotes for strings, escape inner quotes as \\".
+- Default result cap is first(10) for unbounded "show me" questions unless an aggregation makes the result naturally small.
+- Never produce SQL or destructive operations.
+`;
+
+// src/commands/telegram.ts
+async function telegramServeCommand(opts) {
+  const token = opts.botToken ?? process.env.PIPEQUERY_TG_BOT_TOKEN;
+  if (!token) {
+    log.error(
+      "Bot token required. Pass --bot-token <token> or set PIPEQUERY_TG_BOT_TOKEN."
+    );
+    process.exit(1);
+  }
+  const anthropicKey = opts.anthropicKey ?? process.env.ANTHROPIC_API_KEY;
+  const provider = await buildProvider2(opts.attach);
+  const nl = anthropicKey ? createNLTranslator(provider, { apiKey: anthropicKey }) : void 0;
+  const bot = buildBot(token, provider, {
+    allowUsers: opts.allowUser ?? [],
+    nl
+  });
+  const me = await bot.api.getMe();
+  log.success(`Telegram bot listening as @${me.username} (id ${me.id})`);
+  if (nl) {
+    log.info("Natural-language translation enabled (claude-haiku-4-5).");
+  } else {
+    log.dim("Natural-language translation disabled. Pass --anthropic-key or set ANTHROPIC_API_KEY to enable.");
+  }
+  if (!opts.allowUser || opts.allowUser.length === 0) {
+    log.warn("No --allow-user set: anyone with the bot username can query. Add allowlist for production.");
+  }
+  log.info("Press Ctrl+C to stop.");
+  const shutdown = async () => {
+    log.info("Stopping bot...");
+    await bot.stop();
+    await provider.dispose();
+    process.exit(0);
+  };
+  process.on("SIGINT", () => void shutdown());
+  process.on("SIGTERM", () => void shutdown());
+  await bot.start();
+}
+async function buildProvider2(attachUrl) {
+  if (attachUrl) {
+    return new AttachedProvider(attachUrl);
+  }
+  const cwd = process.cwd();
+  const { config } = await loadConfig(cwd);
+  return new LocalProvider(config, cwd);
+}
+
+// src/commands/watch.ts
+import chalk7 from "chalk";
+async function watchListCommand() {
+  const cwd = process.cwd();
+  const { config } = await loadConfig(cwd);
+  const watches = config.watches ?? {};
+  const entries2 = Object.entries(watches);
+  if (entries2.length === 0) {
+    log.dim("No watches configured. Add one with: pq watch add <name>");
+    return;
+  }
+  console.log(chalk7.bold("Watches:\n"));
+  for (const [name, w] of entries2) {
+    const interval = w.interval ?? "60s";
+    const fireWhen = w.fireWhen ?? "when_non_empty";
+    const channels = Object.keys(w.notify).join(", ") || "<none>";
+    console.log(`  ${chalk7.bold(name)}  ${chalk7.dim(`every ${interval} \u2022 ${fireWhen}`)}`);
+    console.log(`    ${chalk7.dim("query:  ")}${w.query}`);
+    console.log(`    ${chalk7.dim("notify: ")}${channels}`);
+  }
+}
+async function watchAddCommand(name, opts) {
+  const cwd = process.cwd();
+  const { config, path: configPath } = await loadConfig(cwd);
+  if (!opts.telegramChatId) {
+    throw new Error("--telegram-chat-id is required (only Telegram notifier supported in v1)");
+  }
+  const fireWhen = opts.fireWhen ?? "when_non_empty";
+  if (!["when_non_empty", "when_empty", "on_change"].includes(fireWhen)) {
+    throw new Error(`--fire-when must be one of: when_non_empty, when_empty, on_change`);
+  }
+  const watch3 = {
+    query: opts.query,
+    ...opts.interval ? { interval: opts.interval } : {},
+    fireWhen,
+    notify: {
+      telegram: {
+        chatId: parseChatId(opts.telegramChatId),
+        ...opts.telegramBotToken ? { botToken: opts.telegramBotToken } : {},
+        ...opts.telegramMessage ? { message: opts.telegramMessage } : {}
+      }
+    }
+  };
+  config.watches = config.watches ?? {};
+  config.watches[name] = watch3;
+  await saveConfig(config, configPath);
+  log.success(`Watch "${name}" added. Restart \`pq serve\` to activate.`);
+}
+async function watchRemoveCommand(name) {
+  const cwd = process.cwd();
+  const { config, path: configPath } = await loadConfig(cwd);
+  if (!config.watches?.[name]) {
+    log.error(`Watch "${name}" not found`);
+    return;
+  }
+  delete config.watches[name];
+  await saveConfig(config, configPath);
+  log.success(`Watch "${name}" removed. Restart \`pq serve\` to apply.`);
+}
+function parseChatId(input) {
+  if (/^-?\d+$/.test(input)) {
+    const n = Number(input);
+    if (Number.isFinite(n) && Number.isSafeInteger(n)) return n;
+  }
+  return input;
+}
+
 // src/commands/completion.ts
 var BASH_COMPLETION = `###-begin-pq-completions-###
 _pq_completions() {
@@ -5385,7 +6252,7 @@ async function stopCommand(opts) {
 // src/commands/repl.ts
 import { createInterface } from "readline";
 import { spawnSync } from "child_process";
-import chalk7 from "chalk";
+import chalk8 from "chalk";
 var COMMANDS = {
   help: "Show available commands",
   serve: "Start the server (serve -d for daemon, serve --stop to stop)",
@@ -5403,15 +6270,15 @@ async function startRepl() {
   let serverUrl = null;
   try {
     serverUrl = await getServerUrl();
-    log.success(`Connected to server at ${chalk7.white.bold(serverUrl)}`);
+    log.success(`Connected to server at ${chalk8.white.bold(serverUrl)}`);
   } catch {
     log.warn("No running server found. Start one with: pq serve");
   }
-  console.log(chalk7.dim('  Type "help" for available commands, "exit" to quit.\n'));
+  console.log(chalk8.dim('  Type "help" for available commands, "exit" to quit.\n'));
   const rl = createInterface({
     input: process.stdin,
     output: process.stdout,
-    prompt: chalk7.hex("#06b6d4").bold("  pq > "),
+    prompt: chalk8.hex("#06b6d4").bold("  pq > "),
     terminal: true
   });
   rl.prompt();
@@ -5428,7 +6295,7 @@ async function startRepl() {
         case "help":
           console.log();
           for (const [name, desc] of Object.entries(COMMANDS)) {
-            console.log(`  ${chalk7.hex("#06b6d4")(name.padEnd(12))} ${chalk7.dim(desc)}`);
+            console.log(`  ${chalk8.hex("#06b6d4")(name.padEnd(12))} ${chalk8.dim(desc)}`);
           }
           console.log();
           break;
@@ -5475,7 +6342,7 @@ async function startRepl() {
           });
           try {
             serverUrl = await getServerUrl();
-            log.success(`Connected to server at ${chalk7.white.bold(serverUrl)}`);
+            log.success(`Connected to server at ${chalk8.white.bold(serverUrl)}`);
           } catch {
           }
           rl.resume();
@@ -5503,7 +6370,7 @@ async function startRepl() {
           break;
         case "exit":
         case "quit":
-          console.log(chalk7.dim("  Goodbye.\n"));
+          console.log(chalk8.dim("  Goodbye.\n"));
           rl.close();
           process.exit(0);
           break;
@@ -5547,20 +6414,20 @@ function printTable(rows) {
     const maxData = rows.reduce((max, row) => Math.max(max, formatCell3(row[col]).length), 0);
     return Math.max(col.length, maxData);
   });
-  const header = columns.map((col, i) => chalk7.hex("#06b6d4").bold(col.padEnd(widths[i]))).join("  ");
-  const separator = widths.map((w) => chalk7.dim("\u2500".repeat(w))).join(chalk7.dim("\u2500\u2500"));
+  const header = columns.map((col, i) => chalk8.hex("#06b6d4").bold(col.padEnd(widths[i]))).join("  ");
+  const separator = widths.map((w) => chalk8.dim("\u2500".repeat(w))).join(chalk8.dim("\u2500\u2500"));
   console.log();
   console.log(`  ${header}`);
   console.log(`  ${separator}`);
   for (const row of rows) {
     const line = columns.map((col, i) => {
       const val = formatCell3(row[col]);
-      return typeof row[col] === "number" ? chalk7.hex("#f59e0b")(val.padStart(widths[i])) : val.padEnd(widths[i]);
+      return typeof row[col] === "number" ? chalk8.hex("#f59e0b")(val.padStart(widths[i])) : val.padEnd(widths[i]);
     }).join("  ");
     console.log(`  ${line}`);
   }
   console.log();
-  console.log(chalk7.dim(`  ${rows.length} row(s)`));
+  console.log(chalk8.dim(`  ${rows.length} row(s)`));
   console.log();
 }
 function formatCell3(value) {
@@ -5578,12 +6445,13 @@ async function fetchAndPrint(serverUrl, path, key) {
 }
 
 // src/index.ts
+var collectRepeated = (value, acc) => [...acc, value];
 var program = new Command();
 program.name("pq").description("PipeQuery CLI \u2014 data sources, aggregations, APIs, and terminal dashboards").version("0.1.0").addHelpText("beforeAll", () => {
   printBanner();
   return "";
 }).configureHelp({
-  subcommandTerm: (cmd) => chalk8.hex("#06b6d4")(cmd.name()) + (cmd.usage() ? " " + chalk8.dim(cmd.usage()) : "")
+  subcommandTerm: (cmd) => chalk9.hex("#06b6d4")(cmd.name()) + (cmd.usage() ? " " + chalk9.dim(cmd.usage()) : "")
 });
 program.command("init").description("Create a pipequery.yaml config file").action(initCommand);
 program.command("serve").description("Start the PipeQuery server").option("-p, --port <port>", "Server port", parseInt).option("-H, --host <host>", "Server host").option("-d, --daemon", "Run as a background daemon").option("--stop", "Stop a running daemon").action(serveCommand);
@@ -5606,6 +6474,12 @@ remote.command("status").description("Check remote server health").action(remote
 var mcp = program.command("mcp").description("Model Context Protocol server for AI clients");
 mcp.command("serve").description("Start an MCP server exposing pipequery as tools (for Claude, Cursor, Copilot, etc.)").option("--http", "Serve over HTTP/SSE instead of stdio").option("-p, --port <port>", "HTTP port (when --http is set)", parseInt).option("-H, --host <host>", "HTTP host (when --http is set)").option("--attach <url>", "Attach to a running `pq serve` instance at the given URL instead of loading pipequery.yaml locally").option("--auth-token <token>", "Require Authorization: Bearer <token> on HTTP requests. Falls back to $PIPEQUERY_MCP_TOKEN. Without either, the endpoint is unauthenticated.").action(mcpServeCommand);
 mcp.command("inspect").description("Print the MCP tool schemas as JSON (useful for directory submission / debugging)").option("--attach <url>", "Attach to a running `pq serve` instance at the given URL instead of loading pipequery.yaml locally").action(mcpInspectCommand);
+var telegram = program.command("telegram").description("Telegram bot transport for pipequery");
+telegram.command("serve").description("Run a Telegram bot that exposes pipequery commands (/query, /sources, /describe, /endpoints, /call) plus natural-language queries when --anthropic-key is set").option("-t, --bot-token <token>", "Telegram bot token (or set $PIPEQUERY_TG_BOT_TOKEN)").option("--attach <url>", "Attach to a running `pq serve` instance instead of loading pipequery.yaml locally").option("--allow-user <handle>", "Allowlist a user (numeric id or @username); repeatable. With no allowlist, anyone with the bot username can query.", collectRepeated, []).option("--anthropic-key <key>", "Anthropic API key (or set $ANTHROPIC_API_KEY) \u2014 enables natural-language \u2192 pipequery translation on plain-text messages via claude-haiku-4-5.").action(telegramServeCommand);
+var watch2 = program.command("watch").description("Manage alert watches (query \u2192 notification when condition fires)");
+watch2.command("list").description("List configured watches").action(watchListCommand);
+watch2.command("add <name>").description("Add a watch that fires a notification when its query result triggers the configured condition").requiredOption("-q, --query <expression>", "PipeQuery expression to evaluate on each tick").option("-i, --interval <duration>", "Poll interval (e.g., 30s, 5m). Default 60s.").option("-f, --fire-when <mode>", "Fire condition: when_non_empty (default), when_empty, on_change").option("--telegram-chat-id <id>", "Telegram chat / channel / group ID to notify").option("--telegram-bot-token <token>", "Bot token override (defaults to $PIPEQUERY_TG_BOT_TOKEN)").option("--telegram-message <template>", "Optional message template; supports {{ .field }} from the first row, plus {{ .count }}, {{ .watchName }}, {{ .reason }}").action(watchAddCommand);
+watch2.command("remove <name>").description("Remove a watch").action(watchRemoveCommand);
 program.command("stop").description("Stop the running PipeQuery server (daemon or foreground)").option("-f, --force", "Force kill (SIGKILL instead of SIGTERM)").action(stopCommand);
 program.command("completion").description("Generate shell completion script").option("-s, --shell <shell>", "Shell type: bash, zsh, fish").action(completionCommand);
 if (process.argv.length <= 2) {