@vaultgradient/pipequery-cli 0.3.2

package/src/commands/repl.ts

@@ -0,0 +1,222 @@
+import { createInterface } from 'node:readline';
+import { spawnSync } from 'node:child_process';
+import chalk from 'chalk';
+import { printCompactBanner } from '../utils/banner.js';
+import { log } from '../utils/logger.js';
+import { getServerUrl } from '../utils/server-discovery.js';
+
+const COMMANDS: Record<string, string> = {
+  help: 'Show available commands',
+  serve: 'Start the server (serve -d for daemon, serve --stop to stop)',
+  query: 'Run a PipeQuery expression (e.g. query products | first(5))',
+  sources: 'List data sources',
+  endpoints: 'List API endpoints',
+  status: 'Show server status',
+  dashboard: 'Launch the interactive TUI dashboard',
+  monitor: 'Launch the live server monitor',
+  clear: 'Clear the screen',
+  exit: 'Exit the REPL',
+};
+
+export async function startRepl() {
+  printCompactBanner();
+
+  let serverUrl: string | null = null;
+  try {
+    serverUrl = await getServerUrl();
+    log.success(`Connected to server at ${chalk.white.bold(serverUrl)}`);
+  } catch {
+    log.warn('No running server found. Start one with: pq serve');
+  }
+  console.log(chalk.dim('  Type "help" for available commands, "exit" to quit.\n'));
+
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    prompt: chalk.hex('#06b6d4').bold('  pq > '),
+    terminal: true,
+  });
+
+  rl.prompt();
+
+  rl.on('line', async (line) => {
+    const input = line.trim();
+    if (!input) {
+      rl.prompt();
+      return;
+    }
+
+    const [cmd, ...rest] = input.split(/\s+/);
+    const args = rest.join(' ');
+
+    try {
+      switch (cmd) {
+        case 'help':
+          console.log();
+          for (const [name, desc] of Object.entries(COMMANDS)) {
+            console.log(`  ${chalk.hex('#06b6d4')(name.padEnd(12))} ${chalk.dim(desc)}`);
+          }
+          console.log();
+          break;
+
+        case 'query':
+        case 'q':
+          if (!args) {
+            log.warn('Usage: query <expression>');
+            break;
+          }
+          if (!serverUrl) {
+            log.error('No server running. Start one with: pq serve');
+            break;
+          }
+          await runQuery(serverUrl, args);
+          break;
+
+        case 'sources':
+          if (!serverUrl) { log.error('No server running.'); break; }
+          await fetchAndPrint(serverUrl, '/api/_control/sources', 'sources');
+          break;
+
+        case 'endpoints':
+          if (!serverUrl) { log.error('No server running.'); break; }
+          await fetchAndPrint(serverUrl, '/api/_control/endpoints', 'endpoints');
+          break;
+
+        case 'status':
+          if (!serverUrl) { log.error('No server running.'); break; }
+          await fetchAndPrint(serverUrl, '/status', null);
+          break;
+
+        case 'serve': {
+          const serveArgs = ['serve'];
+          if (args) serveArgs.push(...args.split(/\s+/));
+          rl.pause();
+          spawnSync(process.execPath, [process.argv[1], ...serveArgs], {
+            cwd: process.cwd(),
+            stdio: 'inherit',
+          });
+          // Re-check server connection after serve
+          try {
+            serverUrl = await getServerUrl();
+            log.success(`Connected to server at ${chalk.white.bold(serverUrl)}`);
+          } catch { /* server may not be running */ }
+          rl.resume();
+          break;
+        }
+
+        case 'dashboard':
+          rl.pause();
+          spawnSync(process.execPath, [process.argv[1], 'dashboard', '-n', args || 'main'], {
+            cwd: process.cwd(),
+            stdio: 'inherit',
+          });
+          rl.resume();
+          break;
+
+        case 'monitor':
+          rl.pause();
+          spawnSync(process.execPath, [process.argv[1], 'monitor'], {
+            cwd: process.cwd(),
+            stdio: 'inherit',
+          });
+          rl.resume();
+          break;
+
+        case 'clear':
+          process.stdout.write('\x1B[2J\x1B[H');
+          printCompactBanner();
+          break;
+
+        case 'exit':
+        case 'quit':
+          console.log(chalk.dim('  Goodbye.\n'));
+          rl.close();
+          process.exit(0);
+          break;
+
+        default:
+          log.warn(`Unknown command: ${cmd}. Type "help" for available commands.`);
+      }
+    } catch (err) {
+      log.error(err instanceof Error ? err.message : String(err));
+    }
+
+    rl.prompt();
+  });
+
+  rl.on('close', () => {
+    process.exit(0);
+  });
+}
+
+async function runQuery(serverUrl: string, expression: string) {
+  const res = await fetch(`${serverUrl}/api/_control/query`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ query: expression }),
+  });
+
+  const json = (await res.json()) as { ok: boolean; result?: unknown; error?: string };
+  if (!json.ok) {
+    log.error(json.error ?? 'Query failed');
+    return;
+  }
+
+  const result = json.result;
+  if (Array.isArray(result) && result.length > 0 && typeof result[0] === 'object') {
+    printTable(result as Record<string, unknown>[]);
+  } else {
+    console.log(JSON.stringify(result, null, 2));
+  }
+}
+
+function printTable(rows: Record<string, unknown>[]) {
+  if (rows.length === 0) {
+    log.dim('(empty result)');
+    return;
+  }
+
+  const columns = Object.keys(rows[0]);
+  const widths = columns.map((col) => {
+    const maxData = rows.reduce((max, row) => Math.max(max, formatCell(row[col]).length), 0);
+    return Math.max(col.length, maxData);
+  });
+
+  const header = columns.map((col, i) => chalk.hex('#06b6d4').bold(col.padEnd(widths[i]))).join('  ');
+  const separator = widths.map((w) => chalk.dim('─'.repeat(w))).join(chalk.dim('──'));
+
+  console.log();
+  console.log(`  ${header}`);
+  console.log(`  ${separator}`);
+
+  for (const row of rows) {
+    const line = columns
+      .map((col, i) => {
+        const val = formatCell(row[col]);
+        return typeof row[col] === 'number'
+          ? chalk.hex('#f59e0b')(val.padStart(widths[i]))
+          : val.padEnd(widths[i]);
+      })
+      .join('  ');
+    console.log(`  ${line}`);
+  }
+
+  console.log();
+  console.log(chalk.dim(`  ${rows.length} row(s)`));
+  console.log();
+}
+
+function formatCell(value: unknown): string {
+  if (value == null) return '';
+  if (typeof value === 'number') return Number.isInteger(value) ? String(value) : value.toFixed(2);
+  return String(value);
+}
+
+async function fetchAndPrint(serverUrl: string, path: string, key: string | null) {
+  const res = await fetch(`${serverUrl}${path}`);
+  const json = await res.json();
+  const data = key ? (json as Record<string, unknown>)[key] : json;
+  console.log();
+  console.log(JSON.stringify(data, null, 2));
+  console.log();
+}

package/src/commands/serve.ts

@@ -0,0 +1,122 @@
+import { writeFile, mkdir, readFile, unlink } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { loadConfig } from '../config/loader.js';
+import { createServer } from '../server/app.js';
+import { log } from '../utils/logger.js';
+import { printCompactBanner, printServerStartup } from '../utils/banner.js';
+
+export async function serveCommand(opts: { port?: number; host?: string; daemon?: boolean; stop?: boolean }) {
+  const cwd = process.cwd();
+  const pqDir = resolve(cwd, '.pipequery');
+  const serverJsonPath = resolve(pqDir, 'server.json');
+
+  // Handle --stop flag
+  if (opts.stop) {
+    return stopDaemon(serverJsonPath);
+  }
+
+  const { config, path: configPath } = await loadConfig(cwd);
+  const port = opts.port ?? config.server.port;
+  const host = opts.host ?? config.server.host;
+
+  // Daemon mode: fork a detached child process
+  if (opts.daemon) {
+    return startDaemon(cwd, port, host);
+  }
+
+  // Foreground mode
+  const { app, sourceManager } = await createServer(config, configPath, cwd);
+
+  await mkdir(pqDir, { recursive: true });
+  const logPath = resolve(pqDir, 'server.log');
+  await writeFile(serverJsonPath, JSON.stringify({ url: `http://localhost:${port}`, pid: process.pid, daemon: false, log: logPath }));
+
+  await app.listen({ port, host });
+
+  const sourceCount = sourceManager.getSourceNames().length;
+  const endpointCount = Object.keys(config.endpoints).length;
+  const url = `http://${host === '0.0.0.0' ? 'localhost' : host}:${port}`;
+
+  printCompactBanner();
+  printServerStartup({ url, sourceCount, endpointCount });
+
+  // Graceful shutdown
+  const shutdown = async () => {
+    log.dim('\nShutting down...');
+    await sourceManager.dispose();
+    await app.close();
+    try { await unlink(serverJsonPath); } catch {}
+    process.exit(0);
+  };
+
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+}
+
+async function startDaemon(cwd: string, port: number, host: string) {
+  const pqDir = resolve(cwd, '.pipequery');
+  const serverJsonPath = resolve(pqDir, 'server.json');
+  const logPath = resolve(pqDir, 'server.log');
+
+  // Check if already running
+  if (existsSync(serverJsonPath)) {
+    try {
+      const info = JSON.parse(await readFile(serverJsonPath, 'utf-8')) as { url: string; pid: number };
+      const res = await fetch(`${info.url}/health`).catch(() => null);
+      if (res?.ok) {
+        log.warn(`Server already running at ${info.url} (PID: ${info.pid})`);
+        return;
+      }
+    } catch {
+      // Stale server.json, proceed
+    }
+  }
+
+  await mkdir(pqDir, { recursive: true });
+
+  // Find the current script to re-run it in foreground mode
+  const scriptPath = process.argv[1];
+  const args = ['serve', '--port', String(port), '--host', host];
+
+  const out = await import('node:fs').then(fs => fs.openSync(logPath, 'a'));
+  const child = spawn(process.execPath, [scriptPath, ...args], {
+    cwd,
+    detached: true,
+    stdio: ['ignore', out, out],
+    env: { ...process.env, PQ_DAEMON: '1' },
+  });
+
+  child.unref();
+
+  // Write server info with daemon PID
+  await writeFile(serverJsonPath, JSON.stringify({
+    url: `http://localhost:${port}`,
+    pid: child.pid,
+    daemon: true,
+    log: logPath,
+  }));
+
+  log.success(`PipeQuery server started in background (PID: ${child.pid})`);
+  log.dim(`Logs: ${logPath}`);
+  log.dim(`Stop with: pq serve --stop`);
+}
+
+async function stopDaemon(serverJsonPath: string) {
+  if (!existsSync(serverJsonPath)) {
+    log.error('No running server found.');
+    return;
+  }
+
+  try {
+    const info = JSON.parse(await readFile(serverJsonPath, 'utf-8')) as { pid: number; url: string };
+    process.kill(info.pid, 'SIGTERM');
+    await unlink(serverJsonPath);
+    log.success(`Server stopped (PID: ${info.pid})`);
+  } catch (err) {
+    log.error(`Failed to stop server: ${err instanceof Error ? err.message : err}`);
+    // Clean up stale file
+    try { await unlink(serverJsonPath); } catch {}
+  }
+}

package/src/commands/source.ts

@@ -0,0 +1,150 @@
+import chalk from 'chalk';
+import { loadConfig, saveConfig } from '../config/loader.js';
+import { getServerUrl } from '../utils/server-discovery.js';
+import { log } from '../utils/logger.js';
+import type { SourceConfig } from '../config/schema.js';
+
+export async function sourceListCommand() {
+  const cwd = process.cwd();
+
+  // Try live server first, fall back to config
+  try {
+    const serverUrl = await getServerUrl();
+    const res = await fetch(`${serverUrl}/api/_control/sources`);
+    const statuses = await res.json() as Record<string, { healthy: boolean; rowCount: number; lastFetch: string | null; error?: string }>;
+
+    if (Object.keys(statuses).length === 0) {
+      log.dim('No sources configured. Add one with: pq source add <name>');
+      return;
+    }
+
+    console.log(chalk.bold('Sources:\n'));
+    for (const [name, status] of Object.entries(statuses)) {
+      const icon = status.healthy ? chalk.green('●') : chalk.red('●');
+      const rows = chalk.dim(`${status.rowCount} rows`);
+      const err = status.error ? chalk.red(` (${status.error})`) : '';
+      console.log(`  ${icon} ${chalk.bold(name)}  ${rows}${err}`);
+    }
+  } catch {
+    // Server not running — read from config
+    const { config } = await loadConfig(cwd);
+    const sources = Object.entries(config.sources);
+
+    if (sources.length === 0) {
+      log.dim('No sources configured. Add one with: pq source add <name>');
+      return;
+    }
+
+    console.log(chalk.bold('Sources (server not running):\n'));
+    for (const [name, src] of sources) {
+      const type = chalk.cyan(src.type);
+      const detail = 'url' in src ? chalk.dim(src.url) : 'path' in src ? chalk.dim(src.path) : '';
+      console.log(`  ○ ${chalk.bold(name)}  ${type}  ${detail}`);
+    }
+  }
+}
+
+export async function sourceAddCommand(name: string, opts: {
+  type: string;
+  url?: string;
+  interval?: string;
+  dataPath?: string;
+  path?: string;
+  watch?: boolean;
+}) {
+  const cwd = process.cwd();
+  const { config, path: configPath } = await loadConfig(cwd);
+
+  let sourceConfig: SourceConfig;
+
+  switch (opts.type) {
+    case 'rest':
+      if (!opts.url) throw new Error('--url is required for REST sources');
+      sourceConfig = {
+        type: 'rest',
+        url: opts.url,
+        interval: opts.interval ?? '30s',
+        ...(opts.dataPath ? { dataPath: opts.dataPath } : {}),
+      };
+      break;
+    case 'websocket':
+      if (!opts.url) throw new Error('--url is required for WebSocket sources');
+      sourceConfig = { type: 'websocket', url: opts.url };
+      break;
+    case 'file':
+      if (!opts.path) throw new Error('--path is required for file sources');
+      sourceConfig = {
+        type: 'file',
+        path: opts.path,
+        ...(opts.watch ? { watch: true } : {}),
+      };
+      break;
+    default:
+      throw new Error(`Unknown source type: ${opts.type}. Use: rest, websocket, file`);
+  }
+
+  // Save to config
+  config.sources[name] = sourceConfig;
+  await saveConfig(config, configPath);
+
+  // If server is running, hot-add the source
+  try {
+    const serverUrl = await getServerUrl();
+    const res = await fetch(`${serverUrl}/api/_control/sources`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ name, config: sourceConfig }),
+    });
+    const json = await res.json() as { ok: boolean; status?: { rowCount: number } };
+    if (json.ok) {
+      log.success(`Source "${name}" added and live (${json.status?.rowCount ?? 0} rows)`);
+      return;
+    }
+  } catch {
+    // Server not running
+  }
+
+  log.success(`Source "${name}" added to config. Start server with: pq serve`);
+}
+
+export async function sourceRemoveCommand(name: string) {
+  const cwd = process.cwd();
+  const { config, path: configPath } = await loadConfig(cwd);
+
+  if (!config.sources[name]) {
+    log.error(`Source "${name}" not found`);
+    return;
+  }
+
+  delete config.sources[name];
+  await saveConfig(config, configPath);
+
+  // If server is running, hot-remove
+  try {
+    const serverUrl = await getServerUrl();
+    await fetch(`${serverUrl}/api/_control/sources/${encodeURIComponent(name)}`, { method: 'DELETE' });
+    log.success(`Source "${name}" removed (live)`);
+    return;
+  } catch {
+    // Server not running
+  }
+
+  log.success(`Source "${name}" removed from config`);
+}
+
+export async function sourceTestCommand(name: string) {
+  const serverUrl = await getServerUrl();
+  const res = await fetch(`${serverUrl}/api/_control/sources/${encodeURIComponent(name)}/test`, { method: 'POST' });
+  const json = await res.json() as { ok: boolean; rowCount?: number; sample?: unknown[]; error?: string };
+
+  if (!json.ok) {
+    log.error(json.error ?? 'Test failed');
+    return;
+  }
+
+  log.success(`Source "${name}": ${json.rowCount} rows`);
+  if (json.sample && json.sample.length > 0) {
+    console.log(chalk.dim('\nSample:'));
+    console.log(JSON.stringify(json.sample, null, 2));
+  }
+}

package/src/commands/stop.ts

@@ -0,0 +1,50 @@
+import { readFile, unlink } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import { log } from '../utils/logger.js';
+
+export async function stopCommand(opts: { force?: boolean }) {
+  const cwd = process.cwd();
+  const serverJsonPath = resolve(cwd, '.pipequery', 'server.json');
+
+  if (!existsSync(serverJsonPath)) {
+    log.error('No running server found.');
+    log.dim('Start one with: pq serve  or  pq serve -d');
+    return;
+  }
+
+  let info: { pid: number; url: string; daemon?: boolean };
+  try {
+    info = JSON.parse(await readFile(serverJsonPath, 'utf-8'));
+  } catch {
+    log.error('Could not read server info. Cleaning up stale file.');
+    try { await unlink(serverJsonPath); } catch {}
+    return;
+  }
+
+  // Check if process is actually running
+  let alive = false;
+  try {
+    process.kill(info.pid, 0); // signal 0 = just check existence
+    alive = true;
+  } catch {
+    // Process not running
+  }
+
+  if (!alive) {
+    log.warn(`Server (PID: ${info.pid}) is not running. Cleaning up stale state.`);
+    try { await unlink(serverJsonPath); } catch {}
+    return;
+  }
+
+  // Send signal
+  const signal = opts.force ? 'SIGKILL' : 'SIGTERM';
+  try {
+    process.kill(info.pid, signal);
+    log.success(`Server stopped (PID: ${info.pid})${info.daemon ? ' [daemon]' : ''}`);
+  } catch (err) {
+    log.error(`Failed to stop server: ${err instanceof Error ? err.message : err}`);
+  }
+
+  try { await unlink(serverJsonPath); } catch {}
+}

package/src/config/defaults.ts

@@ -0,0 +1,48 @@
+import type { PipeQueryConfig } from './schema.js';
+
+export const DEFAULT_CONFIG: PipeQueryConfig = {
+  server: {
+    port: 3000,
+    host: '0.0.0.0',
+  },
+  sources: {},
+  endpoints: {},
+  dashboards: {},
+};
+
+export const STARTER_YAML = `# PipeQuery Configuration
+# Docs: https://github.com/andreadito/pipequery
+
+server:
+  port: 3000
+  host: 0.0.0.0
+
+# Data sources — REST APIs, WebSockets, files, or inline JSON
+sources:
+  # Example: crypto prices from CoinCap
+  # crypto:
+  #   type: rest
+  #   url: https://api.coincap.io/v2/assets
+  #   dataPath: data
+  #   interval: 30s
+  #
+  # orders:
+  #   type: file
+  #   path: ./data/orders.csv
+  #   watch: true
+
+# API endpoints — expose PipeQuery results as REST APIs
+endpoints: {}
+  # /api/top-coins:
+  #   query: "crypto | sort(market_cap desc) | first(10)"
+  #   cache: 30s
+
+# Terminal dashboards
+dashboards: {}
+  # main:
+  #   refresh: 10s
+  #   panels:
+  #     - title: Top Assets
+  #       query: "crypto | sort(market_cap desc) | first(10)"
+  #       viz: table
+`;

package/src/config/loader.ts

@@ -0,0 +1,37 @@
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { readYaml, writeYaml } from '../utils/yaml.js';
+import { DEFAULT_CONFIG } from './defaults.js';
+import type { PipeQueryConfig } from './schema.js';
+
+const CONFIG_NAMES = ['pipequery.yaml', 'pipequery.yml'];
+
+export function findConfigPath(cwd = process.cwd()): string | null {
+  for (const name of CONFIG_NAMES) {
+    const p = resolve(cwd, name);
+    if (existsSync(p)) return p;
+  }
+  return null;
+}
+
+export async function loadConfig(cwd = process.cwd()): Promise<{ config: PipeQueryConfig; path: string }> {
+  const configPath = findConfigPath(cwd);
+  if (!configPath) {
+    throw new Error('No pipequery.yaml found. Run `pq init` to create one.');
+  }
+
+  const raw = await readYaml<Partial<PipeQueryConfig>>(configPath);
+  const config: PipeQueryConfig = {
+    server: { ...DEFAULT_CONFIG.server, ...raw.server },
+    remote: raw.remote,
+    sources: raw.sources ?? {},
+    endpoints: raw.endpoints ?? {},
+    dashboards: raw.dashboards ?? {},
+  };
+
+  return { config, path: configPath };
+}
+
+export async function saveConfig(config: PipeQueryConfig, configPath: string): Promise<void> {
+  await writeYaml(configPath, config);
+}

package/src/config/schema.ts

@@ -0,0 +1,73 @@
+export interface PipeQueryConfig {
+  server: ServerConfig;
+  remote?: RemoteConfig;
+  sources: Record<string, SourceConfig>;
+  endpoints: Record<string, EndpointConfig>;
+  dashboards: Record<string, DashboardConfig>;
+}
+
+export interface ServerConfig {
+  port: number;
+  host: string;
+}
+
+export interface RemoteConfig {
+  url: string;
+}
+
+// ─── Source configs ──────────────────────────────────────────────────────────
+
+export type SourceConfig =
+  | RestSourceConfig
+  | WebSocketSourceConfig
+  | FileSourceConfig
+  | StaticSourceConfig;
+
+export interface RestSourceConfig {
+  type: 'rest';
+  url: string;
+  params?: Record<string, string>;
+  headers?: Record<string, string>;
+  dataPath?: string;
+  interval?: string;
+}
+
+export interface WebSocketSourceConfig {
+  type: 'websocket';
+  url: string;
+  maxBuffer?: number;
+}
+
+export interface FileSourceConfig {
+  type: 'file';
+  path: string;
+  format?: 'json' | 'csv';
+  watch?: boolean;
+}
+
+export interface StaticSourceConfig {
+  type: 'static';
+  data: unknown[];
+}
+
+// ─── Endpoint config ─────────────────────────────────────────────────────────
+
+export interface EndpointConfig {
+  query: string;
+  cache?: string;
+  method?: string;
+}
+
+// ─── Dashboard config ────────────────────────────────────────────────────────
+
+export interface DashboardConfig {
+  refresh?: string;
+  panels: PanelConfig[];
+}
+
+export interface PanelConfig {
+  title: string;
+  query: string;
+  viz: 'table' | 'bar' | 'sparkline' | 'stat' | 'orderbook' | 'heatmap' | 'candle' | 'auto';
+  size?: 'full' | 'half' | 'stat';
+}