@vaultgradient/pipequery-cli 0.7.0 → 0.10.0

package/README.md

@@ -1,14 +1,14 @@
 # pq — PipeQuery CLI
 
-A command-line tool for building data pipelines, REST APIs, and terminal dashboards using PipeQuery expressions.
+A command-line tool for building data pipelines, live API endpoints, terminal dashboards, MCP servers, and Telegram bots — all driven by PipeQuery expressions.
 
-Connect to any data source (REST APIs, WebSockets, files, Postgres, MySQL, SQLite, Kafka), run pipe-based queries to transform and aggregate data, then expose results as API endpoints or visualize them as rich terminal charts.
+Connect to any of 11 data sources (REST, WebSocket, file, static, Postgres, MySQL, SQLite, Kafka, Snowflake, ClickHouse, MongoDB), run pipe-based queries to transform and aggregate data, then expose results as API endpoints, surface them in a TUI, hand them to an AI agent over MCP, or chat with them on Telegram.
 
 **Create API endpoints on the fly** — run `pq endpoint add /api/prices -q "crypto | sort(price desc)"` and instantly get a live JSON endpoint, no config file needed.
 
-**Give your AI agent live data** — `pq mcp serve` exposes every configured source to any Model Context Protocol client (Claude Desktop, Claude Code, Cursor, Copilot). Your AI can now query your REST APIs, files, Postgres / MySQL / SQLite databases, Kafka streams, and WebSocket feeds directly.
+**Give your AI agent live data** — `pq mcp serve` exposes every configured source to any Model Context Protocol client (Claude Desktop, Claude Code, Cursor, Copilot). Pipe expressions targeting Postgres / MySQL / Snowflake / ClickHouse compile to native SQL automatically; targeting MongoDB compile to `find()` / `aggregate()` plans. No in-memory materialization for those engines; the AI gets native-engine performance.
 
-**Use it from Telegram** — `pq telegram serve` runs a Telegram bot that maps the same MCP commands to chat (`/query`, `/sources`, `/describe`, `/call`). Pair with `pq watch add` to push alerts to a Telegram channel when a query result transitions (`when_non_empty`, `when_empty`, or `on_change`).
+**Use it from Telegram** — `pq telegram serve` runs a Telegram bot that maps the same MCP commands to chat (`/query`, `/sources`, `/describe`, `/call`). Pass `--anthropic-key` to enable natural-language queries (Claude Haiku 4.5 translates plain English into pipequery). Pass `--log-file ./bot.jsonl` to record every event for `jq`/SIEM analysis. Pair with `pq watch add` to push alerts to a Telegram channel when a query result transitions (`when_non_empty`, `when_empty`, or `on_change`).
 
 ## Installation
 
@@ -114,15 +114,81 @@ pq source test coins
 pq source remove coins
 ```
 
-Source types:
-- **rest** — Polls a REST API at a configurable interval
-- **websocket** — Streams data from a WebSocket connection
-- **file** — Reads JSON or CSV files, optionally watches for changes
-- **static** — Inline JSON data defined in config
-- **postgres** — Polls a Postgres query. Supports `${ENV_VAR}` interpolation in the connection URL so credentials stay out of `pipequery.yaml`. Options: `-u` URL, `-q` query, `-i` interval, `--ssl <require\|no-verify\|false>`, `--max-rows <n>` (default 10000).
-- **mysql** — Polls a MySQL (or MariaDB) query. Same env-var interpolation and `--ssl` / `--max-rows` options as `postgres`.
-- **sqlite** — Polls a query against a local SQLite file (or `:memory:`). Opens read-only by default (pass `--no-readonly` to open read-write). Options: `-p` path, `-q` query, `-i` interval, `--max-rows <n>`, `--no-readonly`.
-- **kafka** — Streams messages from a Kafka (or Kafka-compatible, e.g. Redpanda) topic into a bounded ring buffer. Each message is decoded per `valueFormat` and spread into a row alongside `_kafka_topic`/`_kafka_partition`/`_kafka_offset`/`_kafka_timestamp`/`_kafka_key` metadata. Auto-generates a per-process consumer group so each pipequery instance sees the full firehose; set `groupId` explicitly to load-balance across replicas. Options: `--brokers` (comma list, supports `${ENV_VAR}`), `--topic`, `--group-id`, `--from-beginning`, `--value-format <json\|string\|raw>`, `--max-buffer <n>` (default 1000), `--ssl true`. SASL is config-only (not CLI-exposed yet).
+Snowflake / ClickHouse / MongoDB are configured directly in `pipequery.yaml` (richer config than the CLI flags expose):
+
+```yaml
+sources:
+  warehouse:
+    type: snowflake
+    account: "${SF_ACCOUNT}"          # myorg-myaccount
+    username: "${SF_USER}"
+    password: "${SF_PASS}"
+    database: ANALYTICS
+    schema: PUBLIC
+    warehouse: COMPUTE_WH
+    query: "SELECT * FROM events WHERE ts > DATEADD(day, -1, CURRENT_TIMESTAMP)"
+
+  metrics:
+    type: clickhouse
+    url: "https://${CH_HOST}:8443"
+    username: "${CH_USER}"
+    password: "${CH_PASS}"
+    database: default
+    query: "SELECT * FROM metrics WHERE ts > now() - INTERVAL 1 HOUR"
+
+  users:
+    type: mongodb
+    url: "mongodb://${DB_USER}:${DB_PASS}@cluster.example.com/?authSource=admin"
+    database: app
+    collection: users
+    filter: { active: true }          # default filter, AND-merged with push-down where()
+
+  binance_btc:
+    type: websocket
+    url: wss://stream.binance.com:9443/ws
+    subscribe:                        # required by every exchange feed
+      - { method: SUBSCRIBE, params: [btcusdt@ticker], id: 1 }
+    heartbeat:
+      payload: { method: PING }
+      interval: 30s
+```
+
+REST sources support `${ENV_VAR}` interpolation in `url`, `headers`, `params`, and `auth.token`, plus an `auth: { kind: bearer, token }` helper:
+
+```yaml
+sources:
+  github_issues:
+    type: rest
+    url: "https://api.github.com/repos/${REPO}/issues"
+    auth:
+      kind: bearer
+      token: "${GITHUB_TOKEN}"
+    interval: 5m
+```
+
+### Source types
+
+- **rest** — Polls a REST API at a configurable interval. `${ENV_VAR}` interpolation in url/headers/params/auth.token. Optional `auth: { kind: bearer, token }` helper.
+- **websocket** — Streams data from a WebSocket connection. Optional `subscribe` payload (single object or array) sent immediately after connect — required by every exchange feed (Binance / Coinbase / Kraken / OKX / Bybit / Deribit / Polygon / Alpaca). Re-sent on every reconnect. Optional `heartbeat: { payload, interval }` keepalive.
+- **file** — Reads JSON or CSV files, optionally watches for changes via `chokidar`.
+- **static** — Inline JSON data defined in config.
+- **postgres** — Polls a Postgres query. `${ENV_VAR}` URL interpolation. SSL: `require` (default), `no-verify`, `false`. Safety `maxRows` cap (default 10000). **Push-down auto-routing**: where/sort/first/select/distinct/rollup/aggregates compile to native SQL.
+- **mysql** / MariaDB — Same pattern + push-down as Postgres, MySQL dialect (backticks + `?` placeholders).
+- **sqlite** — Polls a query against a local SQLite file (or `:memory:`). Opens read-only by default (pass `--no-readonly` to open read-write). No push-down today.
+- **kafka** / Redpanda — Streams messages into a bounded ring buffer. Each message is decoded per `valueFormat` (`json` / `string` / `raw`) and spread into a row alongside `_kafka_topic`/`_kafka_partition`/`_kafka_offset`/`_kafka_timestamp`/`_kafka_key` metadata. Auto-generates a per-process consumer group; set `groupId` explicitly to load-balance across replicas. Options: `--brokers` (comma list, supports `${ENV_VAR}`), `--topic`, `--group-id`, `--from-beginning`, `--value-format`, `--max-buffer`, `--ssl true`. SASL is config-only.
+- **snowflake** — Polls a SELECT against Snowflake. `account` / `username` / `password` / `database` / `schema` / `warehouse` / `role` all support `${ENV_VAR}`. **Push-down**: same operator + aggregate set as Postgres; double-quoted identifiers, `?` placeholders.
+- **clickhouse** — Polls a SELECT against ClickHouse over HTTP/HTTPS. URL + creds support `${ENV_VAR}`. **Push-down**: same operator + aggregate set; backtick identifiers; literal values inlined (escaped) rather than bound, since the HTTP client uses `{name:Type}` named binds that need per-param type tagging.
+- **mongodb** — Polls `find()` against a Mongo collection. Optional yaml `filter` is `$and`-merged with any push-down `where()` predicates. **Push-down**: `where`/`sort`/`first`/bare-field `select` → `find()` plan; grouping (`rollup` / pipeline-terminal aggregates) → `aggregate()` pipeline. Aggregate functions: `sum` / `avg` / `min` / `max` / `count` / `distinct_count`. `_id` stripped from result rows by default.
+
+### Push-down auto-routing
+
+Pipe expressions targeting a Postgres / MySQL / Snowflake / ClickHouse / MongoDB source are compiled to native SQL or Mongo plans and run on the database directly — no in-memory materialization. The dispatch is automatic and transparent: the same `query()` / `runQuery()` call surface is used everywhere, and unsupported pipeline shapes (e.g. `where` after `rollup`, exotic aggregates like `percentile`/`vwap`) silently fall back to the in-process engine.
+
+Operators pushed (SQL engines): `where`, `sort`, `first`, `select` (with arithmetic + aliases), `distinct()` (full-row), `rollup(keys, aggregates...)`, pipeline-terminal aggregates (`| sum(field)`, `| count()`, etc.). Aggregate functions translated to portable SQL: `sum`, `avg`, `min`, `max`, `count`, `distinct_count`.
+
+Operators pushed (Mongo): same operator set, with `find()` for non-grouping pipelines and `aggregate()` for grouping.
+
+What stays in-process: anything the compiler declines (multi-segment field paths, exotic aggregates, `where` after grouping, `groupBy` without `rollup`, `flatten`, `pivot`, `transpose`, `reduce`, `map`, `join` between sources from different engines, custom expression shapes). The AI agent doesn't need to know which path runs — both produce the same row shape.
 
 ### `pq endpoint`
 
@@ -305,6 +371,25 @@ Then in Telegram: `top 5 most expensive paid orders` → bot replies with the tr
 
 The translator uses prompt caching for both the system prompt (always-stable DSL grammar) and the per-tenant schema preamble (source list + inferred fields), so repeated queries are cheap. The schema preamble refreshes every minute.
 
+### Debug / monitor — structured event log
+
+Every command, NL query, and unauthorized attempt is printed as a colored human-readable line on stderr — so you can see who's hitting the bot, what they're asking, and how it's being translated as it happens. Pass `--log-file ./bot.jsonl` to also append one JSON object per line for `jq`-style analysis or feeding into a SIEM.
+
+```bash
+pq telegram serve --allow-user @yourname --log-file ./bot.jsonl
+```
+
+```
+21:15:03 ✓ @andreadito  /sources                        8 rows  12ms
+21:15:24 ✓ @andreadito  "top 5 paid orders"             5 rows  847ms
+                        → orders | where(status == 'paid') | sort(total desc) | first(5)
+21:15:47 🔒 @bob         unauthorized
+21:17:00 ⚠ @andreadito  "drop the orders table"         not answerable
+                        → PipeQuery is read-only and cannot drop tables.
+```
+
+JSONL fields per event: `ts`, `kind` (`command` / `nl` / `unauthorized`), `user`, plus `cmd` / `args` / `outcome` / `rowCount` / `latencyMs` / `error` / `text` / `expression` / `explanation` as applicable. Writes are fire-and-forget so a slow disk doesn't back-pressure incoming Telegram messages.
+
 ## Watch — alerts to Telegram
 
 `pq watch add` registers a query that runs on every interval; when its result transitions (becomes non-empty, becomes empty, or changes content), pipequery posts a notification to a Telegram chat / channel.

package/__tests__/clickhouse-pushdown-compile.test.ts

@@ -0,0 +1,121 @@
+/**
+ * Unit tests for compileClickhousePushdown — no ClickHouse needed.
+ *
+ * ClickHouse INLINES literal values (vs. the bind-then-placeholder path
+ * Postgres / MySQL / Snowflake take), so these tests focus on:
+ *   1. The string-escape contract (no SQL injection possible)
+ *   2. Identifier backticks
+ *   3. Operator-set parity with the other dialects
+ *   4. Empty params array (because everything is inlined)
+ */
+import { describe, expect, it } from 'vitest';
+import { parseQuery } from '../src/engine.js';
+import { compileClickhousePushdown } from '../src/server/sources/pushdown/clickhouse.js';
+
+const BASE = 'SELECT * FROM events';
+
+function compile(expression: string) {
+  const pipeline = parseQuery(expression);
+  return compileClickhousePushdown(pipeline, BASE);
+}
+
+describe('compileClickhousePushdown — dialect surface', () => {
+  it('quotes identifiers with backticks', () => {
+    const r = compile('events | sort(amount desc) | first(5)');
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    expect(r.compiled.sql).toContain('`amount`');
+    expect(r.compiled.sql).not.toContain('"amount"');
+  });
+
+  it('inlines literals — params array stays empty', () => {
+    const r = compile("events | where(status == 'paid' && amount > 100)");
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    expect(r.compiled.params).toEqual([]);
+    expect(r.compiled.sql).toContain("'paid'");
+    expect(r.compiled.sql).toContain('100');
+    // No ?, no $N placeholders anywhere.
+    expect(r.compiled.sql).not.toContain('?');
+    expect(r.compiled.sql).not.toContain('$1');
+  });
+
+  it('escapes single quotes inside string literals', () => {
+    const r = compile('events | where(customer == "O\'Brien")');
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    // The inlined literal must have the apostrophe escaped so it can't
+    // close the string early.
+    expect(r.compiled.sql).toContain("'O\\'Brien'");
+  });
+
+  it('escapes backslashes inside string literals (no double-escape)', () => {
+    const r = compile('events | where(path == "C:\\\\users")');
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    // Each backslash in the original string becomes a doubled backslash
+    // in the SQL — that's 2 bytes per source byte. "C:\\users" is 8
+    // characters in the source string (C : \ \ u s e r s actually no
+    // wait it's the JS-escaped form so the actual string is "C:\users"
+    // = 8 chars including 1 backslash). After escape: "C:\\\\users" =
+    // 10 chars including 2 backslashes. Quoted: 12.
+    expect(r.compiled.sql).toContain("'C:\\\\users'");
+  });
+
+  it('cannot be SQL-injected — apostrophe in string is escaped, not closing the literal', () => {
+    const r = compile('events | where(customer == "Robert\'); DROP TABLE events; --")');
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    // The bytes "DROP TABLE" do appear in the SQL — they're inside a quoted
+    // string literal, which is harmless. What matters is that the closing
+    // apostrophe is escaped (`\'`) so the literal can't terminate early
+    // and let the trailing `; DROP TABLE …; --` reach the parser as code.
+    expect(r.compiled.sql).toContain("\\'");
+    // Substring check: the original apostrophe lives between two backslash
+    // escapes — i.e. `Robert\');` should appear as `Robert\\\'); …` in the
+    // emitted SQL. That confirms the apostrophe was rewritten before the
+    // ); could close the string and start a new statement.
+    expect(r.compiled.sql).toContain("Robert\\');");
+  });
+
+  it('numbers, booleans, and null inline directly', () => {
+    const r1 = compile('events | where(amount > 99.5)');
+    if (r1.ok) expect(r1.compiled.sql).toContain('99.5');
+
+    // Boolean → 1 / 0 (ClickHouse uses UInt8 for booleans).
+    const r2 = compile('events | where(active == true)');
+    if (r2.ok) expect(r2.compiled.sql).toContain('= 1');
+
+    const r3 = compile('events | where(deleted_at == null)');
+    if (r3.ok) expect(r3.compiled.sql).toContain('IS NULL');
+  });
+});
+
+describe('compileClickhousePushdown — operator parity', () => {
+  it('rollup with GROUP BY + aggregates compiles', () => {
+    const r = compile('events | rollup(severity, sum(amount) as total, count() as n) | sort(total desc) | first(10)');
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    expect(r.compiled.sql).toContain('SUM(`amount`) AS `total`');
+    expect(r.compiled.sql).toContain('COUNT(*) AS `n`');
+    expect(r.compiled.sql).toContain('GROUP BY `severity`');
+    expect(r.compiled.sql).toContain('ORDER BY `total` DESC');
+  });
+
+  it('full-row distinct compiles', () => {
+    const r = compile('events | distinct()');
+    expect(r.ok).toBe(true);
+    if (!r.ok) return;
+    expect(r.compiled.sql).toMatch(/^SELECT DISTINCT \* FROM/);
+  });
+
+  it('declines unsupported aggregates (e.g. percentile)', () => {
+    const r = compile('events | rollup(percentile(amount, 0.95) as p95)');
+    expect(r.ok).toBe(false);
+  });
+
+  it('declines where AFTER rollup', () => {
+    const r = compile('events | rollup(severity, sum(amount) as t) | where(t > 100)');
+    expect(r.ok).toBe(false);
+  });
+});

package/__tests__/event-log.test.ts

@@ -0,0 +1,267 @@
+/**
+ * Telegram event-log tests.
+ *
+ * Two surfaces under test:
+ *   1. The pretty formatter — strings only, run with chalk.level=0 so no
+ *      ANSI codes are emitted; assertions look for substrings/values.
+ *   2. The JSONL file writer — backed by a real temp file on disk; verifies
+ *      one JSON object per line, with the documented field shapes.
+ *
+ * No Telegram, no network.
+ */
+import { afterEach, beforeAll, beforeEach, describe, expect, it } from 'vitest';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import chalk from 'chalk';
+import { createEventLogger, formatPretty, type BotEvent } from '../src/telegram/event-log.js';
+
+beforeAll(() => {
+  // No ANSI codes in test assertions — easier to write substring checks.
+  chalk.level = 0;
+});
+
+const FIXED_TS = new Date('2026-04-26T21:15:03.412Z');
+
+describe('formatPretty — command events', () => {
+  it('formats a successful command with row count + latency', () => {
+    const out = formatPretty(
+      {
+        kind: 'command',
+        user: { id: 1, username: 'andreadito' },
+        cmd: '/sources',
+        outcome: 'success',
+        rowCount: 8,
+        latencyMs: 12,
+      },
+      FIXED_TS,
+    );
+    expect(out).toContain('@andreadito');
+    expect(out).toContain('/sources');
+    expect(out).toContain('✓');
+    expect(out).toContain('8 rows');
+    expect(out).toContain('12ms');
+  });
+
+  it('singularizes "1 row"', () => {
+    const out = formatPretty(
+      {
+        kind: 'command',
+        user: { id: 1, username: 'a' },
+        cmd: '/describe',
+        args: 'orders',
+        outcome: 'success',
+        rowCount: 1,
+        latencyMs: 5,
+      },
+      FIXED_TS,
+    );
+    expect(out).toContain('1 row');
+    expect(out).not.toContain('1 rows');
+  });
+
+  it('shows the command args inline', () => {
+    const out = formatPretty(
+      {
+        kind: 'command',
+        user: { id: 1, username: 'a' },
+        cmd: '/describe',
+        args: 'orders',
+        outcome: 'success',
+        rowCount: 5,
+        latencyMs: 7,
+      },
+      FIXED_TS,
+    );
+    expect(out).toContain('/describe orders');
+  });
+
+  it('truncates long args', () => {
+    const longArg = 'a'.repeat(200);
+    const out = formatPretty(
+      {
+        kind: 'command',
+        user: { id: 1, username: 'a' },
+        cmd: '/query',
+        args: longArg,
+        outcome: 'success',
+        rowCount: 0,
+        latencyMs: 1,
+      },
+      FIXED_TS,
+    );
+    expect(out).toContain('…');
+    expect(out.length).toBeLessThan(200);
+  });
+
+  it('formats a failed command with error message', () => {
+    const out = formatPretty(
+      {
+        kind: 'command',
+        user: { id: 1, username: 'a' },
+        cmd: '/query',
+        args: 'foo',
+        outcome: 'error',
+        latencyMs: 3,
+        error: 'parse error: unexpected token',
+      },
+      FIXED_TS,
+    );
+    expect(out).toContain('✗');
+    expect(out).toContain('parse error');
+  });
+});
+
+describe('formatPretty — natural-language events', () => {
+  it('formats a successful NL query with a continuation showing the translated expression', () => {
+    const out = formatPretty(
+      {
+        kind: 'nl',
+        user: { id: 1, username: 'andreadito' },
+        text: 'top 5 paid orders',
+        expression: 'orders | where(status == "paid") | sort(total desc) | first(5)',
+        explanation: 'Top 5 paid orders by total.',
+        outcome: 'success',
+        rowCount: 5,
+        latencyMs: 847,
+      },
+      FIXED_TS,
+    );
+    expect(out).toContain('"top 5 paid orders"');
+    expect(out).toContain('5 rows');
+    expect(out).toContain('847ms');
+    // Continuation line under the action column shows the expression.
+    expect(out).toContain('→ orders | where');
+    // Two lines (primary + continuation).
+    expect(out.split('\n')).toHaveLength(2);
+  });
+
+  it('formats not-answerable with the model explanation on a continuation line', () => {
+    const out = formatPretty(
+      {
+        kind: 'nl',
+        user: { id: 1, username: 'a' },
+        text: 'drop the orders table',
+        explanation: 'PipeQuery is read-only and cannot drop tables.',
+        outcome: 'not_answerable',
+        latencyMs: 412,
+      },
+      FIXED_TS,
+    );
+    expect(out).toContain('⚠');
+    expect(out).toContain('not answerable');
+    expect(out).toContain('PipeQuery is read-only');
+    // Two lines.
+    expect(out.split('\n')).toHaveLength(2);
+  });
+
+  it('formats an NL error inline (no continuation)', () => {
+    const out = formatPretty(
+      {
+        kind: 'nl',
+        user: { id: 1, username: 'a' },
+        text: 'something',
+        outcome: 'error',
+        latencyMs: 30,
+        error: 'translator returned non-JSON',
+      },
+      FIXED_TS,
+    );
+    expect(out).toContain('✗');
+    expect(out).toContain('translator returned non-JSON');
+    expect(out.split('\n')).toHaveLength(1);
+  });
+});
+
+describe('formatPretty — unauthorized', () => {
+  it('formats an unauthorized event with id when no username', () => {
+    const out = formatPretty({ kind: 'unauthorized', user: { id: 12345 } }, FIXED_TS);
+    expect(out).toContain('🔒');
+    expect(out).toContain('id:12345');
+    expect(out).toContain('unauthorized');
+  });
+
+  it('uses @username when present', () => {
+    const out = formatPretty({ kind: 'unauthorized', user: { id: 1, username: 'bob' } }, FIXED_TS);
+    expect(out).toContain('@bob');
+  });
+});
+
+describe('createEventLogger — JSONL file output', () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'pq-eventlog-'));
+  });
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it('appends one JSON object per event', async () => {
+    const file = join(dir, 'bot.jsonl');
+    const stderrLines: string[] = [];
+    const logger = createEventLogger({
+      filePath: file,
+      writeStderr: (s) => stderrLines.push(s),
+      now: () => FIXED_TS,
+    });
+
+    const events: BotEvent[] = [
+      { kind: 'command', user: { id: 1, username: 'a' }, cmd: '/sources', outcome: 'success', rowCount: 8, latencyMs: 12 },
+      { kind: 'nl', user: { id: 1, username: 'a' }, text: 'top 5', expression: 'orders | first(5)', explanation: 'Top 5.', outcome: 'success', rowCount: 5, latencyMs: 800 },
+      { kind: 'unauthorized', user: { id: 99, username: 'bob' } },
+    ];
+    for (const e of events) logger.log(e);
+
+    // Give appendFile a tick to flush.
+    await new Promise((r) => setTimeout(r, 50));
+    const content = await readFile(file, 'utf8');
+    const lines = content.trim().split('\n');
+    expect(lines).toHaveLength(3);
+
+    const first = JSON.parse(lines[0]) as Record<string, unknown>;
+    expect(first.kind).toBe('command');
+    expect(first.cmd).toBe('/sources');
+    expect(first.outcome).toBe('success');
+    expect(first.rowCount).toBe(8);
+    expect(first.latencyMs).toBe(12);
+    expect(first.ts).toBe(FIXED_TS.toISOString());
+    expect(first.user).toEqual({ id: 1, username: 'a' });
+
+    const second = JSON.parse(lines[1]) as Record<string, unknown>;
+    expect(second.kind).toBe('nl');
+    expect(second.text).toBe('top 5');
+    expect(second.expression).toBe('orders | first(5)');
+    expect(second.outcome).toBe('success');
+
+    const third = JSON.parse(lines[2]) as Record<string, unknown>;
+    expect(third.kind).toBe('unauthorized');
+    expect(third.user).toEqual({ id: 99, username: 'bob' });
+  });
+
+  it('always writes to stderr regardless of whether a file is configured', async () => {
+    const stderrLines: string[] = [];
+    const logger = createEventLogger({
+      writeStderr: (s) => stderrLines.push(s),
+      now: () => FIXED_TS,
+    });
+    logger.log({ kind: 'command', user: { id: 1 }, cmd: '/sources', outcome: 'success', rowCount: 0, latencyMs: 1 });
+    expect(stderrLines).toHaveLength(1);
+    expect(stderrLines[0]).toContain('/sources');
+  });
+
+  it('omits optional fields from JSONL when absent', async () => {
+    const file = join(dir, 'bot.jsonl');
+    const logger = createEventLogger({
+      filePath: file,
+      writeStderr: () => undefined,
+      now: () => FIXED_TS,
+    });
+    logger.log({ kind: 'command', user: { id: 1 }, cmd: '/help', outcome: 'success', latencyMs: 1 });
+    await new Promise((r) => setTimeout(r, 50));
+    const obj = JSON.parse((await readFile(file, 'utf8')).trim()) as Record<string, unknown>;
+    expect(obj.rowCount).toBeUndefined();
+    expect(obj.error).toBeUndefined();
+    expect(obj.args).toBeUndefined();
+  });
+});