csvql-query 2.5.0 → 2.6.1

package/README.md

@@ -1,8 +1,23 @@
 # csvql-query
 
-Fast SQL queries on CSV files from Node.js — powered by a Zig/SIMD engine via N-API.
+**SQL on CSV files, in place.** No database, no import, no ingest — point a query at the file where it already lives. A Zig/SIMD engine via N-API, with prebuilt binaries for macOS (arm64/x64), Linux (x64/arm64), and Windows (x64). No compiler needed.
 
-The engine streams through the file instead of loading it into memory, so RAM stays flat — tens of MB — regardless of file size. Prebuilt native binaries ship for macOS (arm64/x64), Linux (x64/arm64), and Windows (x64) — no compiler needed.
+The engine streams the file instead of loading it, so RAM stays flat — tens of MB — regardless of file size.
+
+## Try it without installing anything
+
+```bash
+npx csvql-query "SELECT city, COUNT(*) AS n FROM 'data.csv' GROUP BY city ORDER BY n DESC"
+```
+
+File paths go in single quotes inside `FROM`. `npx csvql-query --help` for the rest.
+
+```bash
+npx csvql-query --json "SELECT * FROM 'sales.csv' WHERE amount > 1000 LIMIT 10"
+npx csvql-query -d '\t'  "SELECT * FROM 'data.tsv' LIMIT 3"
+```
+
+Exit codes are meant to be branched on: `0` success, `1` usage error, `2` query error, `3` file/IO error.
 
 ## Install
 
@@ -69,9 +84,35 @@ Operators in `where`: `= != > >= < <=`, combined with `AND` / `OR`. Values are a
 
 `opts`: `{ delimiter, comment, skipEmptyLines }`. TypeScript declarations are bundled.
 
+## For AI agents (MCP)
+
+Pasting a 417 MB CSV into an LLM costs ~230 million tokens — it fits in no context window. Over [MCP](https://modelcontextprotocol.io/), an agent queries the file in place and gets back only the answer, for a few hundred tokens.
+
+The MCP server ships in the standalone binary rather than this package:
+
+```bash
+brew install melihbirim/csvql/csvql
+csvql install          # registers csvql with Claude Code + Claude Desktop
+```
+
+There's also a one-click `.mcpb` extension for Claude Desktop on the [releases page](https://github.com/melihbirim/csvql/releases). Full setup — VS Code Copilot, Claude Desktop, manual config — in the [main README](https://github.com/melihbirim/csvql#mcp).
+
+**Read-only by design.** csvql only runs `SELECT`. It has no `INSERT`/`UPDATE`/`DELETE`/`DROP` and physically cannot modify your data. It makes zero network calls and runs fully air-gapped, so you can put it next to the data instead of shipping files out to an LLM.
+
+## Correctness
+
+csvql treats [DuckDB](https://duckdb.org) as the reference implementation and diffs its own output against it — because an agent can't eyeball a wrong answer the way a human scanning a spreadsheet can.
+
+- **97 differential checks** against DuckDB on every PR, across Linux x86_64 and macOS ARM
+- **553 unit tests**
+- **A differential query generator** runs ~50,000 generated queries against DuckDB nightly; every run appends a row to a public [verification log](https://github.com/melihbirim/csvql/blob/main/VERIFICATION-LOG.md) — wins and losses both
+- Where behavior intentionally differs from DuckDB, it's [documented and audited](https://github.com/melihbirim/csvql/blob/main/CORRECTNESS.md), not hand-waved
+
+Unsupported SQL **errors clearly** rather than silently returning wrong data. That distinction is the entire point.
+
 ## Supported SQL
 
-`SELECT`, `WHERE`, `GROUP BY`, `ORDER BY`, `LIMIT`, `JOIN`, `DISTINCT`, `LIKE`, and `COUNT` / `SUM` / `AVG` / `MIN` / `MAX`.
+`SELECT`, `WHERE`, `GROUP BY`, `HAVING`, `ORDER BY`, `LIMIT`, `JOIN`, `DISTINCT`, `LIKE`, `BETWEEN`, `IN` (including `IN (SELECT ...)` subqueries), `COUNT`/`SUM`/`AVG`/`MIN`/`MAX`, and scalar functions (`UPPER`, `LOWER`, `TRIM`, `LENGTH`, `SUBSTR`, `REPLACE`, `COALESCE`, `CAST`, `ROUND`, …).
 
 ## License
 

package/cli.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+'use strict';
+
+// csvql-query CLI — the zero-install entry point.
+//
+//   npx csvql-query "SELECT city, COUNT(*) FROM 'data.csv' GROUP BY city"
+//
+// This exists so someone can try csvql in one line without adding a
+// dependency or writing a script. It is a thin wrapper over the same N-API
+// module index.js exports — no query logic lives here, so it cannot drift
+// from the library.
+//
+// For the MCP server (what an AI agent connects to), install the standalone
+// binary: `brew install melihbirim/csvql/csvql` then `csvql install`. That
+// server lives in the Zig binary, not in this package — see --help.
+
+const csvql = require('./index.js');
+
+const VERSION = require('./package.json').version;
+
+const HELP = `csvql-query ${VERSION} — SQL on CSV files, in place
+
+USAGE
+  npx csvql-query [options] "<SQL>"
+
+  File paths go in single quotes inside the FROM clause:
+    npx csvql-query "SELECT * FROM 'data.csv' LIMIT 5"
+
+OPTIONS
+  -j, --json              Output JSON instead of CSV
+  -d, --delimiter <c>     Input delimiter (e.g. -d '\\t' for TSV)
+  -c, --comment <s>       Skip lines starting with <s>
+  -s, --skip-empty        Skip blank lines
+  -h, --help              Show this help
+  -v, --version           Show version
+
+EXAMPLES
+  npx csvql-query "SELECT * FROM 'sales.csv' WHERE amount > 1000 LIMIT 10"
+  npx csvql-query "SELECT region, SUM(amount) FROM 'sales.csv' GROUP BY region"
+  npx csvql-query --json "SELECT COUNT(*) AS n FROM 'sales.csv'"
+  npx csvql-query -d '\\t' "SELECT * FROM 'data.tsv' LIMIT 3"
+
+SUPPORTED SQL
+  SELECT, WHERE, GROUP BY, HAVING, ORDER BY, LIMIT, JOIN, DISTINCT, LIKE,
+  IN (incl. subqueries), BETWEEN, COUNT/SUM/AVG/MIN/MAX, and scalar functions.
+  Read-only: there is no INSERT/UPDATE/DELETE/DROP.
+
+FOR AI AGENTS (MCP)
+  This package is the Node library + CLI. The MCP server ships in the
+  standalone binary so an agent can query a multi-GB CSV for a few hundred
+  tokens instead of pasting it into context:
+
+    brew install melihbirim/csvql/csvql   # or grab a release binary
+    csvql install                         # registers it with Claude
+
+  https://github.com/melihbirim/csvql#mcp
+
+EXIT CODES
+  0 success   1 usage error   2 query error   3 file/IO error
+`;
+
+function fail(code, msg) {
+  process.stderr.write(`csvql-query: ${msg}\n`);
+  process.exit(code);
+}
+
+function parseArgs(argv) {
+  const opts = {};
+  let sql = null;
+  let json = false;
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const needsValue = (name) => {
+      const v = argv[++i];
+      if (v === undefined) fail(1, `${name} requires a value`);
+      return v;
+    };
+
+    switch (a) {
+      case '-h':
+      case '--help':
+        process.stdout.write(HELP);
+        process.exit(0);
+        break;
+      case '-v':
+      case '--version':
+        process.stdout.write(`${VERSION}\n`);
+        process.exit(0);
+        break;
+      case '-j':
+      case '--json':
+        json = true;
+        break;
+      case '-d':
+      case '--delimiter':
+        // Accept a literal backslash-t from the shell as a real tab, so
+        // `-d '\t'` works without the caller needing $'\t' quoting.
+        opts.delimiter = needsValue(a).replace(/\\t/g, '\t');
+        break;
+      case '-c':
+      case '--comment':
+        opts.comment = needsValue(a);
+        break;
+      case '-s':
+      case '--skip-empty':
+        opts.skipEmptyLines = true;
+        break;
+      default:
+        if (a.startsWith('-') && a !== '-') fail(1, `unknown option: ${a}`);
+        if (sql !== null) fail(1, 'more than one SQL statement given (quote the whole query)');
+        sql = a;
+    }
+  }
+
+  return { sql, opts, json };
+}
+
+function main() {
+  const { sql, opts, json } = parseArgs(process.argv.slice(2));
+
+  if (sql === null || sql.trim() === '') {
+    process.stderr.write(HELP);
+    process.exit(1);
+  }
+
+  let out;
+  try {
+    out = json ? JSON.stringify(csvql.query(sql, opts), null, 2) : csvql.queryCsv(sql, opts);
+  } catch (err) {
+    // Distinguish "your file is missing" from "your SQL is wrong" so a
+    // script (or an agent) can branch on it, matching the standalone
+    // binary's exit-code contract.
+    const msg = String((err && err.message) || err);
+    const isIO = /ENOENT|no such file|FileNotFound|cannot open|EmptyFile/i.test(msg);
+    fail(isIO ? 3 : 2, msg);
+  }
+
+  process.stdout.write(out.endsWith('\n') ? out : out + '\n');
+}
+
+main();

package/package.json

@@ -1,17 +1,22 @@
 {
   "name": "csvql-query",
-  "version": "2.5.0",
-  "description": "Fast SQL queries on CSV files — Zig/SIMD engine via N-API",
+  "version": "2.6.1",
+  "description": "SQL on CSV files in place — no import, no database. Zig/SIMD engine for Node and AI agents (MCP). Read-only by design.",
   "main": "index.js",
   "types": "index.d.ts",
+  "bin": {
+    "csvql-query": "cli.js"
+  },
   "files": [
     "index.js",
     "index.d.ts",
+    "cli.js",
     "binaries/"
   ],
   "scripts": {
     "build": "zig build node -Doptimize=ReleaseFast && mkdir -p binaries && cp ../zig-out/lib/csvql.node binaries/$(node -p \"process.platform + '-' + process.arch\").node",
     "test": "node test.js",
+    "test:cli": "node test_cli.js",
     "bench": "node bench.js"
   },
   "keywords": [
@@ -24,7 +29,12 @@
     "parser",
     "agent",
     "ai",
-    "mcp"
+    "mcp",
+    "llm",
+    "cli",
+    "duckdb",
+    "analytics",
+    "dataframe"
   ],
   "license": "MIT",
   "repository": {