@vaultgradient/pipequery-cli 0.4.0 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaultgradient/pipequery-cli",
-  "version": "0.4.0",
+  "version": "0.6.1",
   "description": "CLI for PipeQuery — data sources, aggregations, APIs, and terminal dashboards",
   "type": "module",
   "bin": {
@@ -13,6 +13,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
+    "@anthropic-ai/sdk": "^0.91.1",
     "@fastify/cors": "^11.2.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "better-sqlite3": "^12.9.0",
@@ -21,6 +22,7 @@
     "commander": "^14.0.3",
     "csv-parse": "^6.2.1",
     "fastify": "^5.8.5",
+    "grammy": "^1.42.0",
     "ink": "^7.0.1",
     "kafkajs": "^2.2.4",
     "mysql2": "^3.22.2",

package/src/commands/telegram.ts

@@ -0,0 +1,65 @@
+import { loadConfig } from '../config/loader.js';
+import { log } from '../utils/logger.js';
+import { LocalProvider, AttachedProvider, type Provider } from '../mcp/provider.js';
+import { buildBot } from '../telegram/bot.js';
+import { createNLTranslator } from '../telegram/nl.js';
+
+interface TelegramServeOptions {
+  botToken?: string;
+  attach?: string;
+  allowUser?: string[];
+  anthropicKey?: string;
+}
+
+export async function telegramServeCommand(opts: TelegramServeOptions): Promise<void> {
+  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 buildProvider(opts.attach);
+  const nl = anthropicKey
+    ? createNLTranslator(provider, { apiKey: anthropicKey })
+    : undefined;
+
+  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 buildProvider(attachUrl?: string): Promise<Provider> {
+  if (attachUrl) {
+    return new AttachedProvider(attachUrl);
+  }
+  const cwd = process.cwd();
+  const { config } = await loadConfig(cwd);
+  return new LocalProvider(config, cwd);
+}

package/src/commands/watch.ts

@@ -0,0 +1,84 @@
+import chalk from 'chalk';
+import { loadConfig, saveConfig } from '../config/loader.js';
+import { log } from '../utils/logger.js';
+import type { WatchConfig } from '../config/schema.js';
+
+export async function watchListCommand(): Promise<void> {
+  const cwd = process.cwd();
+  const { config } = await loadConfig(cwd);
+  const watches = config.watches ?? {};
+  const entries = Object.entries(watches);
+  if (entries.length === 0) {
+    log.dim('No watches configured. Add one with: pq watch add <name>');
+    return;
+  }
+  console.log(chalk.bold('Watches:\n'));
+  for (const [name, w] of entries) {
+    const interval = w.interval ?? '60s';
+    const fireWhen = w.fireWhen ?? 'when_non_empty';
+    const channels = Object.keys(w.notify).join(', ') || '<none>';
+    console.log(`  ${chalk.bold(name)}  ${chalk.dim(`every ${interval} • ${fireWhen}`)}`);
+    console.log(`    ${chalk.dim('query:  ')}${w.query}`);
+    console.log(`    ${chalk.dim('notify: ')}${channels}`);
+  }
+}
+
+export async function watchAddCommand(name: string, opts: {
+  query: string;
+  interval?: string;
+  fireWhen?: string;
+  telegramChatId?: string;
+  telegramMessage?: string;
+  telegramBotToken?: string;
+}): Promise<void> {
+  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 watch: WatchConfig = {
+    query: opts.query,
+    ...(opts.interval ? { interval: opts.interval } : {}),
+    fireWhen: fireWhen as WatchConfig['fireWhen'],
+    notify: {
+      telegram: {
+        chatId: parseChatId(opts.telegramChatId),
+        ...(opts.telegramBotToken ? { botToken: opts.telegramBotToken } : {}),
+        ...(opts.telegramMessage ? { message: opts.telegramMessage } : {}),
+      },
+    },
+  };
+
+  config.watches = config.watches ?? {};
+  config.watches[name] = watch;
+  await saveConfig(config, configPath);
+  log.success(`Watch "${name}" added. Restart \`pq serve\` to activate.`);
+}
+
+export async function watchRemoveCommand(name: string): Promise<void> {
+  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: string): string | number {
+  // Numeric Telegram chat IDs (e.g. -1001234567890) are large negative
+  // integers that fit in safe-integer range. Keep negatives as numbers.
+  if (/^-?\d+$/.test(input)) {
+    const n = Number(input);
+    if (Number.isFinite(n) && Number.isSafeInteger(n)) return n;
+  }
+  return input;
+}

package/src/config/loader.ts

@@ -27,6 +27,7 @@ export async function loadConfig(cwd = process.cwd()): Promise<{ config: PipeQue
     sources: raw.sources ?? {},
     endpoints: raw.endpoints ?? {},
     dashboards: raw.dashboards ?? {},
+    watches: raw.watches ?? {},
   };
 
   return { config, path: configPath };

package/src/config/schema.ts

@@ -4,6 +4,7 @@ export interface PipeQueryConfig {
   sources: Record<string, SourceConfig>;
   endpoints: Record<string, EndpointConfig>;
   dashboards: Record<string, DashboardConfig>;
+  watches?: Record<string, WatchConfig>;
 }
 
 export interface ServerConfig {
@@ -178,3 +179,47 @@ export interface PanelConfig {
   viz: 'table' | 'bar' | 'sparkline' | 'stat' | 'orderbook' | 'heatmap' | 'candle' | 'auto';
   size?: 'full' | 'half' | 'stat';
 }
+
+// ─── Watches (alerts triggered by a query result) ────────────────────────────
+
+export interface WatchConfig {
+  /** PipeQuery expression to evaluate on each tick. */
+  query: string;
+  /** Poll interval, e.g. "30s", "5m". Defaults to "60s". */
+  interval?: string;
+  /**
+   * When to fire a notification:
+   *   - `when_non_empty` (default): fires on the transition from empty/null
+   *     to non-empty. Doesn't re-fire while still non-empty; re-fires after
+   *     going empty and then non-empty again. Standard alerting shape.
+   *   - `when_empty`: inverse — fires when transitioning to empty (e.g., a
+   *     liveness check that fails when no rows match).
+   *   - `on_change`: fires on any change in the result content. Useful for
+   *     "tell me when this number moves" but can be chatty.
+   */
+  fireWhen?: 'when_non_empty' | 'when_empty' | 'on_change';
+  /** Notification channels. At least one must be configured. */
+  notify: WatchNotify;
+}
+
+export interface WatchNotify {
+  telegram?: TelegramNotifyConfig;
+}
+
+export interface TelegramNotifyConfig {
+  /**
+   * Bot token; supports `${ENV_VAR}` interpolation. If omitted, defaults
+   * to the `PIPEQUERY_TG_BOT_TOKEN` environment variable.
+   */
+  botToken?: string;
+  /** Chat / channel / group ID to post to. */
+  chatId: string | number;
+  /**
+   * Optional message template. `{{ .field }}` expands to the named field
+   * of the FIRST row of the result (most alerts care about a single
+   * triggering row). `{{ .count }}` is special and yields the total row
+   * count. If omitted, the bot posts a default summary line plus the
+   * full result rendered as a Markdown table.
+   */
+  message?: string;
+}

package/src/index.ts

@@ -9,11 +9,16 @@ import { dashboardCommand } from './commands/dashboard.js';
 import { monitorCommand } from './commands/monitor.js';
 import { remoteDeployCommand, remoteConnectCommand, remoteStatusCommand } from './commands/remote.js';
 import { mcpServeCommand, mcpInspectCommand } from './commands/mcp.js';
+import { telegramServeCommand } from './commands/telegram.js';
+import { watchListCommand, watchAddCommand, watchRemoveCommand } from './commands/watch.js';
 import { completionCommand } from './commands/completion.js';
 import { stopCommand } from './commands/stop.js';
 import { startRepl } from './commands/repl.js';
 import { printBanner } from './utils/banner.js';
 
+// Commander helper: accumulate `--allow-user @a --allow-user @b` into an array.
+const collectRepeated = (value: string, acc: string[]): string[] => [...acc, value];
+
 const program = new Command();
 
 program
@@ -169,6 +174,44 @@ mcp
   .option('--attach <url>', 'Attach to a running `pq serve` instance at the given URL instead of loading pipequery.yaml locally')
   .action(mcpInspectCommand);
 
+// ─── pq telegram ─────────────────────────────────────────────────────────────
+
+const 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) — enables natural-language → pipequery translation on plain-text messages via claude-haiku-4-5.')
+  .action(telegramServeCommand);
+
+// ─── pq watch ────────────────────────────────────────────────────────────────
+
+const watch = program.command('watch').description('Manage alert watches (query → notification when condition fires)');
+
+watch
+  .command('list')
+  .description('List configured watches')
+  .action(watchListCommand);
+
+watch
+  .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);
+
+watch
+  .command('remove <name>')
+  .description('Remove a watch')
+  .action(watchRemoveCommand);
+
 // ─── pq stop ────────────────────────────────────────────────────────────────
 
 program

package/src/server/app.ts

@@ -2,6 +2,7 @@ import Fastify from 'fastify';
 import cors from '@fastify/cors';
 import type { PipeQueryConfig, EndpointConfig, SourceConfig } from '../config/schema.js';
 import { SourceManager } from './sources/manager.js';
+import { WatchManager } from './watches/manager.js';
 import { registerHealthRoutes } from './routes/health.js';
 import { registerControlRoutes } from './routes/control.js';
 import { registerDynamicRoutes } from './routes/dynamic.js';
@@ -14,6 +15,7 @@ export interface ServerContext {
   app: ReturnType<typeof Fastify>;
   sourceManager: SourceManager;
   endpoints: Map<string, EndpointConfig>;
+  watchManager: WatchManager;
 }
 
 export async function createServer(
@@ -95,7 +97,14 @@ export async function createServer(
   registerSSERoutes(app, sourceManager);
   registerDynamicRoutes(app, sourceManager, endpoints);
 
+  // Watches: register and start polling. Failures in any single watch are
+  // isolated — see WatchManager for the per-watch error handling.
+  const watchManager = new WatchManager(sourceManager);
+  if (config.watches && Object.keys(config.watches).length > 0) {
+    watchManager.start(config.watches);
+  }
+
   activity.info('Server ready');
 
-  return { app, sourceManager, endpoints };
+  return { app, sourceManager, endpoints, watchManager };
 }

package/src/server/watches/manager.ts

@@ -0,0 +1,177 @@
+/**
+ * Watch manager — polls each configured watch on its interval, evaluates
+ * the pipequery expression against the live source data, and dispatches
+ * notifications when the watch's fire condition is met.
+ *
+ * Lives alongside the existing endpoint registry in createServer(). Same
+ * lifecycle: start when the server boots, stop when it disposes.
+ *
+ * Idempotency model:
+ *   - For `when_non_empty`: track per-watch `lastWasEmpty` boolean. Fire
+ *     only when the previous tick was empty (or first run) and the current
+ *     tick is non-empty. Re-fires after the result goes empty and back.
+ *   - For `when_empty`: the inverse.
+ *   - For `on_change`: track a hash of the last result; fire on hash change.
+ *
+ * All firing is best-effort. If a notifier throws, the error is logged on
+ * stderr and the watch state advances anyway — we don't want one stuck
+ * notifier to wedge an alert pipeline.
+ */
+import { createHash } from 'node:crypto';
+import { query } from '../../engine.js';
+import { parseDuration } from '../../utils/parseDuration.js';
+import * as activity from '../activity-log.js';
+import type { WatchConfig, WatchNotify } from '../../config/schema.js';
+import type { SourceManager } from '../sources/manager.js';
+import type { Notifier } from '../../telegram/notifier.js';
+import { TelegramNotifier } from '../../telegram/notifier.js';
+
+const DEFAULT_INTERVAL_MS = 60_000;
+
+interface WatchState {
+  config: WatchConfig;
+  notifiers: Notifier[];
+  intervalMs: number;
+  timer: ReturnType<typeof setInterval> | null;
+  lastWasEmpty: boolean | null;
+  lastHash: string | null;
+}
+
+export class WatchManager {
+  private watches = new Map<string, WatchState>();
+  private disposed = false;
+
+  constructor(private sourceManager: SourceManager) {}
+
+  start(configs: Record<string, WatchConfig>): void {
+    for (const [name, cfg] of Object.entries(configs)) {
+      try {
+        this.startOne(name, cfg);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        activity.error(`Watch "${name}" failed to start: ${msg}`);
+        process.stderr.write(`[pipequery-watch] "${name}" failed to start: ${msg}\n`);
+      }
+    }
+  }
+
+  private startOne(name: string, cfg: WatchConfig): void {
+    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_MS;
+    const state: WatchState = {
+      config: cfg,
+      notifiers,
+      intervalMs,
+      timer: null,
+      lastWasEmpty: null,
+      lastHash: null,
+    };
+    this.watches.set(name, state);
+    activity.info(`Watch "${name}" registered (every ${cfg.interval ?? '60s'})`);
+
+    // Run once immediately to seed `lastWasEmpty`/`lastHash` — we don't fire
+    // on the very first tick, since "transitioned" requires a previous state.
+    void this.tick(name);
+    state.timer = setInterval(() => void this.tick(name), intervalMs);
+  }
+
+  private async tick(name: string): Promise<void> {
+    if (this.disposed) return;
+    const state = this.watches.get(name);
+    if (!state) return;
+
+    let result: unknown;
+    try {
+      const ctx = this.sourceManager.getContext();
+      result = query(ctx, state.config.query);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      activity.error(`Watch "${name}" query failed: ${msg}`);
+      // Don't advance state on query failure — wait for the next tick.
+      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;
+
+    activity.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);
+          activity.error(`Watch "${name}" notify failed: ${msg}`);
+          process.stderr.write(`[pipequery-watch] "${name}" notify failed: ${msg}\n`);
+        }),
+      ),
+    );
+  }
+
+  stop(name: string): boolean {
+    const state = this.watches.get(name);
+    if (!state) return false;
+    if (state.timer) clearInterval(state.timer);
+    this.watches.delete(name);
+    return true;
+  }
+
+  list(): string[] {
+    return [...this.watches.keys()];
+  }
+
+  dispose(): void {
+    this.disposed = true;
+    for (const state of this.watches.values()) {
+      if (state.timer) clearInterval(state.timer);
+    }
+    this.watches.clear();
+  }
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function buildNotifiers(notify: WatchNotify): Notifier[] {
+  const out: Notifier[] = [];
+  if (notify.telegram) out.push(new TelegramNotifier(notify.telegram));
+  return out;
+}
+
+function isResultEmpty(result: unknown): boolean {
+  if (result === null || result === undefined) return true;
+  if (Array.isArray(result)) return result.length === 0;
+  if (typeof result === 'object') return Object.keys(result as object).length === 0;
+  return false;
+}
+
+function hashResult(result: unknown): string {
+  // Stable JSON for hashing — skip undefined / sort keys.
+  const json = JSON.stringify(result, (_, v) => (v === undefined ? null : v));
+  return createHash('sha256').update(json).digest('hex');
+}