@vaultgradient/pipequery-cli 0.3.2

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@vaultgradient/pipequery-cli",
+  "version": "0.3.2",
+  "description": "CLI for PipeQuery — data sources, aggregations, APIs, and terminal dashboards",
+  "type": "module",
+  "bin": {
+    "pq": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@fastify/cors": "^11.2.0",
+    "chalk": "^5.6.2",
+    "chokidar": "^5.0.0",
+    "commander": "^14.0.3",
+    "csv-parse": "^6.2.1",
+    "fastify": "^5.8.5",
+    "ink": "^7.0.1",
+    "ora": "^9.3.0",
+    "react": "^19.2.5",
+    "ws": "^8.20.0",
+    "yaml": "^2.8.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "@types/react": "^19.2.14",
+    "@types/ws": "^8.18.1",
+    "tsup": "^8.5.1",
+    "typescript": "~6.0.0",
+    "vitest": "^4.1.4"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/andreadito/pipequery.git",
+    "directory": "cli"
+  },
+  "author": "andreadito",
+  "license": "MIT"
+}

package/src/commands/completion.ts

@@ -0,0 +1,167 @@
+import { log } from '../utils/logger.js';
+
+const BASH_COMPLETION = `###-begin-pq-completions-###
+_pq_completions() {
+  local cur prev commands source_cmds endpoint_cmds remote_cmds
+  COMPREPLY=()
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  prev="\${COMP_WORDS[COMP_CWORD-1]}"
+
+  commands="init serve query source endpoint dashboard remote help"
+  source_cmds="list add remove test"
+  endpoint_cmds="list add remove"
+  remote_cmds="deploy connect status"
+
+  case "\${COMP_WORDS[1]}" in
+    source)
+      COMPREPLY=( $(compgen -W "$source_cmds" -- "$cur") )
+      return 0
+      ;;
+    endpoint)
+      COMPREPLY=( $(compgen -W "$endpoint_cmds" -- "$cur") )
+      return 0
+      ;;
+    remote)
+      COMPREPLY=( $(compgen -W "$remote_cmds" -- "$cur") )
+      return 0
+      ;;
+    serve)
+      COMPREPLY=( $(compgen -W "--port --host --daemon --stop" -- "$cur") )
+      return 0
+      ;;
+    query)
+      COMPREPLY=( $(compgen -W "--format" -- "$cur") )
+      return 0
+      ;;
+    dashboard)
+      COMPREPLY=( $(compgen -W "--name" -- "$cur") )
+      return 0
+      ;;
+  esac
+
+  if [[ \${COMP_CWORD} -eq 1 ]]; then
+    COMPREPLY=( $(compgen -W "$commands" -- "$cur") )
+  fi
+
+  return 0
+}
+complete -F _pq_completions pq
+###-end-pq-completions-###`;
+
+const ZSH_COMPLETION = `###-begin-pq-completions-###
+_pq() {
+  local -a commands source_cmds endpoint_cmds remote_cmds
+
+  commands=(
+    'init:Create a pipequery.yaml config file'
+    'serve:Start the PipeQuery server'
+    'query:Run an ad-hoc PipeQuery expression'
+    'source:Manage data sources'
+    'endpoint:Manage API endpoints'
+    'dashboard:Launch the interactive terminal dashboard'
+    'remote:Manage remote deployment'
+  )
+
+  source_cmds=(
+    'list:List configured data sources'
+    'add:Add a data source'
+    'remove:Remove a data source'
+    'test:Test a data source'
+  )
+
+  endpoint_cmds=(
+    'list:List API endpoints'
+    'add:Register an API endpoint'
+    'remove:Remove an API endpoint'
+  )
+
+  remote_cmds=(
+    'deploy:Generate Dockerfile and docker-compose.yaml'
+    'connect:Connect CLI to a remote PipeQuery server'
+    'status:Check remote server health'
+  )
+
+  _arguments -C \\
+    '1: :->command' \\
+    '2: :->subcommand' \\
+    '*::arg:->args'
+
+  case $state in
+    command)
+      _describe 'command' commands
+      ;;
+    subcommand)
+      case $words[2] in
+        source) _describe 'subcommand' source_cmds ;;
+        endpoint) _describe 'subcommand' endpoint_cmds ;;
+        remote) _describe 'subcommand' remote_cmds ;;
+      esac
+      ;;
+  esac
+}
+compdef _pq pq
+###-end-pq-completions-###`;
+
+const FISH_COMPLETION = `###-begin-pq-completions-###
+# Top-level commands
+complete -c pq -f -n '__fish_use_subcommand' -a 'init' -d 'Create a pipequery.yaml config file'
+complete -c pq -f -n '__fish_use_subcommand' -a 'serve' -d 'Start the PipeQuery server'
+complete -c pq -f -n '__fish_use_subcommand' -a 'query' -d 'Run an ad-hoc PipeQuery expression'
+complete -c pq -f -n '__fish_use_subcommand' -a 'source' -d 'Manage data sources'
+complete -c pq -f -n '__fish_use_subcommand' -a 'endpoint' -d 'Manage API endpoints'
+complete -c pq -f -n '__fish_use_subcommand' -a 'dashboard' -d 'Launch the terminal dashboard'
+complete -c pq -f -n '__fish_use_subcommand' -a 'remote' -d 'Manage remote deployment'
+
+# source subcommands
+complete -c pq -f -n '__fish_seen_subcommand_from source' -a 'list' -d 'List data sources'
+complete -c pq -f -n '__fish_seen_subcommand_from source' -a 'add' -d 'Add a data source'
+complete -c pq -f -n '__fish_seen_subcommand_from source' -a 'remove' -d 'Remove a data source'
+complete -c pq -f -n '__fish_seen_subcommand_from source' -a 'test' -d 'Test a data source'
+
+# endpoint subcommands
+complete -c pq -f -n '__fish_seen_subcommand_from endpoint' -a 'list' -d 'List endpoints'
+complete -c pq -f -n '__fish_seen_subcommand_from endpoint' -a 'add' -d 'Add an endpoint'
+complete -c pq -f -n '__fish_seen_subcommand_from endpoint' -a 'remove' -d 'Remove an endpoint'
+
+# remote subcommands
+complete -c pq -f -n '__fish_seen_subcommand_from remote' -a 'deploy' -d 'Generate Docker files'
+complete -c pq -f -n '__fish_seen_subcommand_from remote' -a 'connect' -d 'Connect to remote server'
+complete -c pq -f -n '__fish_seen_subcommand_from remote' -a 'status' -d 'Check remote health'
+
+# serve flags
+complete -c pq -l port -s p -n '__fish_seen_subcommand_from serve' -d 'Server port'
+complete -c pq -l host -s H -n '__fish_seen_subcommand_from serve' -d 'Server host'
+complete -c pq -l daemon -s d -n '__fish_seen_subcommand_from serve' -d 'Run as daemon'
+complete -c pq -l stop -n '__fish_seen_subcommand_from serve' -d 'Stop running daemon'
+###-end-pq-completions-###`;
+
+export async function completionCommand(opts: { shell?: string }) {
+  const shell = opts.shell ?? detectShell();
+
+  switch (shell) {
+    case 'bash':
+      console.log(BASH_COMPLETION);
+      log.dim('\n# Add to ~/.bashrc:');
+      log.dim('# eval "$(pq completion --shell bash)"');
+      break;
+    case 'zsh':
+      console.log(ZSH_COMPLETION);
+      log.dim('\n# Add to ~/.zshrc:');
+      log.dim('# eval "$(pq completion --shell zsh)"');
+      break;
+    case 'fish':
+      console.log(FISH_COMPLETION);
+      log.dim('\n# Save to ~/.config/fish/completions/pq.fish:');
+      log.dim('# pq completion --shell fish > ~/.config/fish/completions/pq.fish');
+      break;
+    default:
+      log.error(`Unknown shell: ${shell}. Use --shell bash|zsh|fish`);
+  }
+}
+
+function detectShell(): string {
+  const shell = process.env.SHELL ?? '';
+  if (shell.includes('zsh')) return 'zsh';
+  if (shell.includes('fish')) return 'fish';
+  return 'bash';
+}

package/src/commands/dashboard.ts

@@ -0,0 +1,44 @@
+import React from 'react';
+import { render } from 'ink';
+import { loadConfig } from '../config/loader.js';
+import { getServerUrl } from '../utils/server-discovery.js';
+import { log } from '../utils/logger.js';
+import { App } from '../tui/App.js';
+import { enableSyncOutput, disableSyncOutput } from '../utils/sync-output.js';
+
+export async function dashboardCommand(opts: { name?: string }) {
+  const dashboardName = opts.name ?? 'main';
+  const cwd = process.cwd();
+  const { config } = await loadConfig(cwd);
+
+  const dashboard = config.dashboards[dashboardName];
+  if (!dashboard) {
+    log.error(`Dashboard "${dashboardName}" not found in config.`);
+    const available = Object.keys(config.dashboards);
+    if (available.length > 0) {
+      log.info(`Available dashboards: ${available.join(', ')}`);
+    } else {
+      log.dim('Add a dashboard section to pipequery.yaml');
+    }
+    return;
+  }
+
+  const serverUrl = await getServerUrl();
+
+  // Enter alternate screen buffer + synchronized output
+  process.stdout.write('\x1B[?1049h');
+  process.stdout.write('\x1B[?25l');
+  enableSyncOutput();
+
+  const { waitUntilExit } = render(
+    React.createElement(App, { serverUrl, dashboard }),
+    { patchConsole: false },
+  );
+
+  await waitUntilExit();
+
+  // Restore
+  disableSyncOutput();
+  process.stdout.write('\x1B[?25h');
+  process.stdout.write('\x1B[?1049l');
+}

package/src/commands/endpoint.ts

@@ -0,0 +1,99 @@
+import chalk from 'chalk';
+import { loadConfig, saveConfig } from '../config/loader.js';
+import { getServerUrl } from '../utils/server-discovery.js';
+import { log } from '../utils/logger.js';
+
+export async function endpointListCommand() {
+  const cwd = process.cwd();
+
+  try {
+    const serverUrl = await getServerUrl();
+    const res = await fetch(`${serverUrl}/api/_control/endpoints`);
+    const endpoints = await res.json() as Record<string, { query: string; cache?: string }>;
+
+    if (Object.keys(endpoints).length === 0) {
+      log.dim('No endpoints configured. Add one with: pq endpoint add <path> --query "<expr>"');
+      return;
+    }
+
+    console.log(chalk.bold('Endpoints:\n'));
+    for (const [path, config] of Object.entries(endpoints)) {
+      const cache = config.cache ? chalk.dim(`(cache: ${config.cache})`) : '';
+      console.log(`  ${chalk.green('GET')} ${chalk.bold(path)}  ${cache}`);
+      console.log(`      ${chalk.dim(config.query)}`);
+    }
+  } catch {
+    const { config } = await loadConfig(cwd);
+    const entries = Object.entries(config.endpoints);
+
+    if (entries.length === 0) {
+      log.dim('No endpoints configured. Add one with: pq endpoint add <path> --query "<expr>"');
+      return;
+    }
+
+    console.log(chalk.bold('Endpoints (server not running):\n'));
+    for (const [path, cfg] of entries) {
+      console.log(`  ${chalk.green('GET')} ${chalk.bold(path)}`);
+      console.log(`      ${chalk.dim(cfg.query)}`);
+    }
+  }
+}
+
+export async function endpointAddCommand(path: string, opts: { query: string; cache?: string }) {
+  const cwd = process.cwd();
+  const { config, path: configPath } = await loadConfig(cwd);
+
+  // Ensure path starts with /
+  const apiPath = path.startsWith('/') ? path : `/${path}`;
+
+  const endpointConfig = {
+    query: opts.query,
+    ...(opts.cache ? { cache: opts.cache } : {}),
+  };
+
+  // Save to config
+  config.endpoints[apiPath] = endpointConfig;
+  await saveConfig(config, configPath);
+
+  // Hot-add if server running
+  try {
+    const serverUrl = await getServerUrl();
+    await fetch(`${serverUrl}/api/_control/endpoints`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ path: apiPath, config: endpointConfig }),
+    });
+    log.success(`Endpoint ${apiPath} registered (live)`);
+    return;
+  } catch {
+    // Server not running
+  }
+
+  log.success(`Endpoint ${apiPath} added to config. Start server with: pq serve`);
+}
+
+export async function endpointRemoveCommand(path: string) {
+  const cwd = process.cwd();
+  const { config, path: configPath } = await loadConfig(cwd);
+
+  const apiPath = path.startsWith('/') ? path : `/${path}`;
+
+  if (!config.endpoints[apiPath]) {
+    log.error(`Endpoint "${apiPath}" not found`);
+    return;
+  }
+
+  delete config.endpoints[apiPath];
+  await saveConfig(config, configPath);
+
+  try {
+    const serverUrl = await getServerUrl();
+    await fetch(`${serverUrl}/api/_control/endpoints/${apiPath.slice(1)}`, { method: 'DELETE' });
+    log.success(`Endpoint ${apiPath} removed (live)`);
+    return;
+  } catch {
+    // Server not running
+  }
+
+  log.success(`Endpoint ${apiPath} removed from config`);
+}

package/src/commands/init.ts

@@ -0,0 +1,20 @@
+import { writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import { log } from '../utils/logger.js';
+import { STARTER_YAML } from '../config/defaults.js';
+import chalk from 'chalk';
+
+export async function initCommand() {
+  const target = resolve(process.cwd(), 'pipequery.yaml');
+
+  if (existsSync(target)) {
+    log.warn('pipequery.yaml already exists in this directory.');
+    return;
+  }
+
+  await writeFile(target, STARTER_YAML, 'utf-8');
+  log.success('Created pipequery.yaml');
+  log.step(`Edit ${chalk.white.bold('pipequery.yaml')} to configure your data sources`);
+  log.step(`Then run ${chalk.white.bold('pq serve')} to start the server`);
+}

package/src/commands/monitor.ts

@@ -0,0 +1,52 @@
+import React from 'react';
+import { render } from 'ink';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { getServerUrl } from '../utils/server-discovery.js';
+import { log } from '../utils/logger.js';
+import { MonitorApp } from '../tui/MonitorApp.js';
+import { enableSyncOutput, disableSyncOutput } from '../utils/sync-output.js';
+
+export async function monitorCommand() {
+  const serverUrl = await getServerUrl();
+
+  // Try to find log path from server discovery
+  const discoveryPath = resolve(process.cwd(), '.pipequery', 'server.json');
+  let logPath: string | undefined;
+
+  if (existsSync(discoveryPath)) {
+    try {
+      const disc = JSON.parse(readFileSync(discoveryPath, 'utf-8')) as { log?: string };
+      if (disc.log && existsSync(disc.log)) {
+        logPath = disc.log;
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  // Fallback log path
+  if (!logPath) {
+    const fallback = resolve(process.cwd(), '.pipequery', 'server.log');
+    if (existsSync(fallback)) {
+      logPath = fallback;
+    }
+  }
+
+  // Enter alternate screen buffer + synchronized output
+  process.stdout.write('\x1B[?1049h');
+  process.stdout.write('\x1B[?25l');
+  enableSyncOutput();
+
+  const { waitUntilExit } = render(
+    React.createElement(MonitorApp, { serverUrl, logPath }),
+    { patchConsole: false },
+  );
+
+  await waitUntilExit();
+
+  // Restore
+  disableSyncOutput();
+  process.stdout.write('\x1B[?25h');
+  process.stdout.write('\x1B[?1049l');
+}

package/src/commands/query.ts

@@ -0,0 +1,81 @@
+import chalk from 'chalk';
+import { getServerUrl } from '../utils/server-discovery.js';
+import { log } from '../utils/logger.js';
+
+export async function queryCommand(expression: string, opts: { format?: string }) {
+  const serverUrl = await getServerUrl();
+
+  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');
+    process.exit(1);
+  }
+
+  const result = json.result;
+
+  if (opts.format === 'json') {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  // Render as table
+  if (Array.isArray(result) && result.length > 0 && typeof result[0] === 'object') {
+    renderTable(result as Record<string, unknown>[]);
+  } else if (typeof result === 'object' && result !== null && !Array.isArray(result)) {
+    renderTable([result as Record<string, unknown>]);
+  } else {
+    console.log(result);
+  }
+}
+
+function renderTable(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);
+  });
+
+  // Header
+  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}`);
+
+  // Rows
+  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);
+}

package/src/commands/remote.ts

@@ -0,0 +1,89 @@
+import { writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { findConfigPath, loadConfig, saveConfig } from '../config/loader.js';
+import { DEFAULT_CONFIG } from '../config/defaults.js';
+import type { PipeQueryConfig } from '../config/schema.js';
+import { log } from '../utils/logger.js';
+import { generateDockerfile, generateDockerCompose, generateDockerignore } from '../docker/templates.js';
+
+export async function remoteDeployCommand() {
+  const cwd = process.cwd();
+  const { config } = await loadConfig(cwd);
+  const port = config.server.port;
+
+  // Generate files
+  await writeFile(resolve(cwd, 'Dockerfile'), generateDockerfile(port));
+  await writeFile(resolve(cwd, 'docker-compose.yaml'), generateDockerCompose(port));
+  await writeFile(resolve(cwd, '.dockerignore'), generateDockerignore());
+
+  log.success('Generated Dockerfile, docker-compose.yaml, and .dockerignore');
+  log.info(`Run: docker compose up -d --build`);
+  log.info(`Then: pq remote connect http://localhost:${port}`);
+}
+
+/**
+ * Load config if it exists, or create a minimal one for remote-only usage.
+ */
+async function loadOrCreateConfig(cwd: string): Promise<{ config: PipeQueryConfig; path: string }> {
+  const existing = findConfigPath(cwd);
+  if (existing) {
+    return loadConfig(cwd);
+  }
+
+  // No local config — create a minimal one for remote connection
+  const configPath = resolve(cwd, 'pipequery.yaml');
+  const config: PipeQueryConfig = {
+    server: { ...DEFAULT_CONFIG.server },
+    sources: {},
+    endpoints: {},
+    dashboards: {},
+  };
+  await saveConfig(config, configPath);
+  return { config, path: configPath };
+}
+
+export async function remoteConnectCommand(url: string) {
+  // Verify the remote server is reachable first
+  try {
+    const res = await fetch(`${url}/health`);
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  } catch (err) {
+    log.error(`Cannot reach ${url}: ${err instanceof Error ? err.message : err}`);
+    return;
+  }
+
+  const cwd = process.cwd();
+  const { config, path: configPath } = await loadOrCreateConfig(cwd);
+
+  config.remote = { url };
+  await saveConfig(config, configPath);
+  log.success(`Connected to remote server at ${url}`);
+}
+
+export async function remoteStatusCommand() {
+  const cwd = process.cwd();
+
+  const existing = findConfigPath(cwd);
+  if (!existing) {
+    log.error('No remote server configured. Use: pq remote connect <url>');
+    return;
+  }
+
+  const { config } = await loadConfig(cwd);
+  const url = config.remote?.url;
+  if (!url) {
+    log.error('No remote server configured. Use: pq remote connect <url>');
+    return;
+  }
+
+  try {
+    const res = await fetch(`${url}/status`);
+    const status = await res.json() as { status: string; uptime: number; sources: Record<string, unknown> };
+
+    log.success(`Remote server at ${url}`);
+    log.info(`Uptime: ${Math.floor(status.uptime / 1000)}s`);
+    log.info(`Sources: ${Object.keys(status.sources).length}`);
+  } catch (err) {
+    log.error(`Cannot reach ${url}: ${err instanceof Error ? err.message : err}`);
+  }
+}