jpath-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 takeaseatventure
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,139 @@
+# jpath-cli
+
+**Query and extract data from JSON with a simple, powerful path syntax.** A focused, zero-dependency CLI — `jq`'s little sibling for the 90% case.
+
+[![tests](https://img.shields.io/badge/tests-40%20pass-brightgreen)]() [![deps](https://img.shields.io/badge/dependencies-0-success)]() [![license](https://img.shields.io/badge/license-MIT-blue)]()
+[![npm](https://img.shields.io/npm/v/jpath-cli)](https://npmjs.com/package/jpath-cli)
+
+---
+
+## Why?
+
+`jq` is brilliant but its filter language is its own dialect with a steep learning curve. For the vast majority of real work — *"give me the `name` field of every user over 30"* — you shouldn't need to reach for a manual. `jpath` uses an intuitive dot/bracket path you already know from JavaScript, adds a tiny filter syntax, and stays **zero-dependency** so it installs instantly and audits clean.
+
+## Install
+
+```bash
+npm install -g jpath-cli
+```
+
+Or run it directly with `npx jpath ...` — no install needed.
+
+## Quickstart
+
+```bash
+# Extract a single value
+echo '{"user":{"name":"Ada","age":36}}' | jpath .user.name
+# "Ada"
+
+# All names from an array
+cat users.json | jpath 'users[*].name'
+
+# Filter + extract
+cat users.json | jpath 'users[?(@.age >= 18)].name'
+
+# Every "id" at any depth
+cat data.json | jpath '..id'
+
+# Pretty table
+cat items.json | jpath '[*]' -o table -k id,name,price
+```
+
+## Path syntax
+
+| Syntax | Meaning | Example |
+|---|---|---|
+| `.foo` | object key `foo` | `.user.name` |
+| `['foo.bar']` | bracket key (supports dots/spaces) | `['weird.key']` |
+| `[0]` | array index | `arr[0]` |
+| `[-1]` | last element | `arr[-1]` |
+| `[*]` | wildcard — all elements / all values | `users[*]` |
+| `[1:4]` | slice (start inclusive, end exclusive) | `arr[1:4]` |
+| `..key` | recursive descent — `key` at any depth | `..id` |
+| `[?(expr)]` | filter — keep matching elements | `[?(@.price > 10)]` |
+
+A leading `$` (root) is accepted and ignored: `$.user.name` ≡ `.user.name`.
+
+## Filter expressions
+
+Inside `[?(...)]`, use `@` to refer to the current element:
+
+| Expression | Matches when… |
+|---|---|
+| `@.active` | `active` is truthy |
+| `!@.deleted` | `deleted` is falsy |
+| `@.age > 30` | numeric comparison (`>=`, `<`, `<=`, `==`, `!=`) |
+| `@.name == 'Ada'` | equality (loose: `"10" == 10`) |
+| `@.tags contains 'go'` | array/string contains |
+| `@.name startsWith 'A'` | string prefix |
+| `@.name =~ /^A/i` | regex match (`/pattern/flags`) |
+| `@.id in [1,2,3]` | membership |
+
+Combine with the element path to pull a field: `users[?(@.age > 30)].name`.
+
+## Output formats (`-o, --output`)
+
+| Format | Description |
+|---|---|
+| `json` | Pretty JSON (default) |
+| `compact` | Minified JSON |
+| `jsonl` | Newline-delimited (one JSON per array item) |
+| `raw` | Raw scalar (no quotes) |
+| `table` | Aligned columns (`-k id,name` to choose) |
+| `keys` | List object keys / array indices |
+| `count` | Length of the result |
+
+## Options
+
+```
+  -o, --output <fmt>   output format
+  -k, --keys <a,b>     columns for table output
+  -i, --indent <n>     JSON indent (default 2)
+  -r, --raw            shortcut for -o raw
+      --null-as <str>  emit this string when the result is null/undefined
+  -v, --version        print version
+  -h, --help           show help
+      --demo           run a built-in demo
+```
+
+## Recipes
+
+```bash
+# Names of active users, one per line
+jpath 'users[?(@.active)].name' data.json -o jsonl
+
+# In-stock products, tabular
+jpath 'products[?(@.stock > 0)]' data.json -o table -k sku,name,price
+
+# Count comments on a post
+jpath 'post.comments[*]' data.json -o count
+
+# Pull every URL out of a deeply-nested config
+jpath '..url' config.json -o jsonl
+
+# Last 3 log entries
+jpath 'logs[-3:]' app.json
+
+# Raw scalar for scripting
+PRICE=$(jpath '.price' quote.json -r)
+```
+
+## As a library
+
+```js
+const { evaluate } = require('jpath');
+
+const data = { users: [{ age: 30 }, { age: 40 }] };
+const over30 = evaluate('users[?(@.age > 30)]', data);
+// [{ age: 40 }]
+```
+
+## Design notes
+
+- **Zero dependencies.** Pure Node.js, no install-time risk, fast cold start.
+- **Safe by construction.** Filter expressions are parsed by a small hand-written evaluator — **no `eval()`, ever.** Untrusted JSON is safe to query.
+- **Predictable missing values.** A missing key or out-of-range index yields `undefined` and a silent exit — ideal for pipelines.
+
+## License
+
+MIT © venture

package/bin/jpath.js

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+// bin/jpath.js — CLI entry point
+'use strict';
+
+const { readFileSync } = require('fs');
+const { evaluate } = require('../lib/path');
+const { formatOutput } = require('../lib/format');
+
+const VERSION = '0.1.0';
+
+function usage() {
+  return `jpath v${VERSION} — query & extract data from JSON
+
+USAGE
+  jpath [options] <path> [file]
+  cat file.json | jpath [options] <path>
+
+PATH SYNTAX
+  .foo                  object key
+  ['weird.key']         bracket key (supports dots/spaces)
+  [0]                   array index ([ -1] = last)
+  [*]                   wildcard (all elements / all values)
+  [1:4]                 slice (start:end)
+  ..key                 recursive descent (key at any depth)
+  [?(@.price > 10)]     filter
+  [?(@.active)]         truthy filter
+  [?(@.name =~ /^A/)]   regex filter
+
+FILTER OPERATORS
+  ==  !=  >  >=  <  <=
+  contains  !contains
+  startsWith  endsWith
+  in  !in
+  =~  (regex; use /pattern/i form)
+
+OUTPUT FORMATS (-o, --output)
+  json       pretty JSON (default)
+  compact    minified JSON
+  jsonl      newline-delimited JSON (one per array item)
+  raw        raw scalar value (no quotes)
+  table      aligned columns
+  keys       list object keys / array indices
+  count      length of result
+
+OPTIONS
+  -o, --output <fmt>   output format (see above)
+  -k, --keys <a,b>     columns for table output
+  -i, --indent <n>     JSON indent (default 2)
+  -r, --raw            shortcut for -o raw
+      --null-as        string to emit when result is null/undefined (default: emits nothing)
+  -v, --version        print version
+  -h, --help           show this help
+      --demo           run a built-in demo
+
+EXAMPLES
+  echo '{"a":{"b":[1,2,3]}}' | jpath .a.b[1]            # -> 2
+  echo '[{"n":1},{"n":2}]'   | jpath '[*].n'            # -> [1,2]
+  cat users.json | jpath '[?(@.age >= 18)].name'        # names of adults
+  cat data.json  | jpath '..id'                          # every 'id' at any depth
+  cat items.json | jpath -o table '[*]' -k id,name,price
+`;
+}
+
+function parseArgs(argv) {
+  const opts = { path: null, file: null, output: 'json', keys: [], indent: 2, raw: false, nullAs: null, demo: false };
+  const args = argv.slice(2);
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '-h' || a === '--help') { opts.help = true; }
+    else if (a === '-v' || a === '--version') { opts.version = true; }
+    else if (a === '-o' || a === '--output') { opts.output = args[++i]; }
+    else if (a === '-k' || a === '--keys') { opts.keys = args[++i].split(',').map((s) => s.trim()); }
+    else if (a === '-i' || a === '--indent') { opts.indent = parseInt(args[++i], 10); }
+    else if (a === '-r' || a === '--raw') { opts.raw = true; opts.output = 'raw'; }
+    else if (a === '--null-as') { opts.nullAs = args[++i]; }
+    else if (a === '--demo') { opts.demo = true; }
+    else if (a.startsWith('-')) { throw new Error(`unknown option: ${a}`); }
+    else if (opts.path == null) { opts.path = a; }
+    else if (opts.file == null) { opts.file = a; }
+    else { throw new Error(`unexpected argument: ${a}`); }
+  }
+  return opts;
+}
+
+function readInput(file) {
+  if (file) return readFileSync(file, 'utf8');
+  // read from stdin if it's not a TTY; otherwise nothing
+  try {
+    return readFileSync(0, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+function runDemo() {
+  const demo = {
+    users: [
+      { id: 1, name: 'Ada', age: 36, role: 'engineer', active: true, tags: ['rust', 'systems'] },
+      { id: 2, name: 'Grace', age: 28, role: 'engineer', active: true, tags: ['go', 'cloud'] },
+      { id: 3, name: 'Linus', age: 54, role: 'maintainer', active: false, tags: ['c', 'kernel'] },
+      { id: 4, name: 'Margaret', age: 41, role: 'engineer', active: true, tags: ['python', 'data'] },
+    ],
+    meta: { total: 4, env: 'prod', nested: { deep: { id: 'hidden' } } },
+  };
+  const json = JSON.stringify(demo);
+  const examples = [
+    ['.users[0].name', 'first user name'],
+    ['.users[-1].name', 'last user name'],
+    ['.users[*].name', 'all names'],
+    ['.users[?(@.age > 30)].name', 'names of users over 30'],
+    ['.users[?(@.tags contains "go")].name', 'users tagged "go"'],
+    ['.users[?(@.active)].name', 'active users'],
+    ['.users[1:3].name', 'slice users 1..3'],
+    ['..id', 'every id at any depth'],
+    ['.users[*].name', null, 'count', 'count of names'],
+  ];
+  console.log(`jpath v${VERSION} — demo\nInput: ${json}\n`);
+  for (const [path, label, fmtOverride, label2] of examples) {
+    const val = evaluate(path, demo);
+    const fmt = fmtOverride || 'json';
+    const out = formatOutput(val, fmt);
+    const title = label2 || label;
+    console.log(`# ${title}`);
+    console.log(`  path: ${path}`);
+    console.log(`  ${out}\n`);
+  }
+}
+
+function main() {
+  let opts;
+  try { opts = parseArgs(process.argv); }
+  catch (e) { process.stderr.write(`error: ${e.message}\n\n${usage()}`); process.exit(2); }
+
+  if (opts.help) { process.stdout.write(usage()); return; }
+  if (opts.version) { process.stdout.write(`jpath v${VERSION}\n`); return; }
+  if (opts.demo) { runDemo(); return; }
+
+  if (opts.path == null) {
+    process.stderr.write(`error: a path argument is required\n\n${usage()}`);
+    process.exit(2);
+  }
+
+  let input;
+  try { input = readInput(opts.file); }
+  catch (e) { process.stderr.write(`error reading input: ${e.message}\n`); process.exit(1); }
+
+  if (!input || !input.trim()) {
+    process.stderr.write(`error: no JSON input (provide a file or pipe JSON via stdin)\n`);
+    process.exit(1);
+  }
+
+  let root;
+  try { root = JSON.parse(input); }
+  catch (e) { process.stderr.write(`error: invalid JSON input: ${e.message}\n`); process.exit(1); }
+
+  let result;
+  try { result = evaluate(opts.path, root); }
+  catch (e) {
+    process.stderr.write(`error: ${e.message}\n`);
+    process.exit(1);
+  }
+
+  if (result === undefined || result === null) {
+    if (opts.nullAs != null) process.stdout.write(opts.nullAs + '\n');
+    else process.stderr.write(''); // no output for null/missing
+    return;
+  }
+
+  let out;
+  try {
+    out = formatOutput(result, opts.output, { indent: opts.indent, keys: opts.keys });
+  } catch (e) {
+    process.stderr.write(`error: ${e.message}\n`); process.exit(1);
+  }
+  process.stdout.write(out + (out.endsWith('\n') ? '' : '\n'));
+}
+
+main();

package/lib/format.js

@@ -0,0 +1,90 @@
+// lib/format.js — output formatters (json, json-compact, jsonl, raw, table, keys, count)
+'use strict';
+
+function formatOutput(value, format, opts = {}) {
+  switch ((format || 'json').toLowerCase()) {
+    case 'json':
+    case 'json5':
+    case 'pretty':
+      return JSON.stringify(value, null, opts.indent == null ? 2 : opts.indent);
+
+    case 'jsonc':
+    case 'compact':
+    case 'min':
+      return JSON.stringify(value);
+
+    case 'jsonl':
+    case 'ndjson': {
+      const arr = Array.isArray(value) ? value : [value];
+      return arr.map((v) => JSON.stringify(v)).join('\n');
+    }
+
+    case 'raw':
+      if (typeof value === 'string') return value;
+      if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+      if (value == null) return 'null';
+      return JSON.stringify(value);
+
+    case 'table':
+    case 'columns': {
+      const arr = Array.isArray(value) ? value : [value];
+      return renderTable(arr, opts.keys);
+    }
+
+    case 'keys': {
+      if (Array.isArray(value)) return value.map((v, i) => String(i)).join('\n');
+      if (value && typeof value === 'object') return Object.keys(value).join('\n');
+      return '';
+    }
+
+    case 'count':
+    case 'len':
+    case 'length': {
+      if (Array.isArray(value)) return String(value.length);
+      if (value && typeof value === 'object') return String(Object.keys(value).length);
+      if (typeof value === 'string') return String(value.length);
+      return value == null ? '0' : '1';
+    }
+
+    default:
+      throw new Error(`Unknown format: ${format}`);
+  }
+}
+
+function pickTableKeys(arr) {
+  const keySet = new Set();
+  for (const item of arr) {
+    if (item && typeof item === 'object' && !Array.isArray(item)) {
+      for (const k of Object.keys(item)) keySet.add(k);
+    }
+  }
+  return [...keySet];
+}
+
+function renderTable(arr, explicitKeys) {
+  const rows = arr.filter((r) => r != null);
+  if (rows.length === 0) return '(empty)';
+  const scalar = rows.every((r) => typeof r !== 'object' || r === null);
+  if (scalar) {
+    return rows.map((r) => String(r)).join('\n');
+  }
+  const keys = explicitKeys && explicitKeys.length ? explicitKeys : pickTableKeys(rows);
+  const cell = (v) => {
+    if (v == null) return '';
+    if (typeof v === 'object') return JSON.stringify(v);
+    return String(v);
+  };
+  const widths = keys.map((k) => Math.max(k.length, ...rows.map((r) => cell(r[k]).length)));
+  const header = keys.map((k, i) => pad(k, widths[i])).join('  ');
+  const sep = widths.map((w) => '-'.repeat(w)).join('  ');
+  const body = rows.map((r) => keys.map((k, i) => pad(cell(r[k]), widths[i])).join('  ')).join('\n');
+  return [header, sep, body].join('\n');
+}
+
+function pad(s, n) {
+  s = String(s);
+  if (s.length >= n) return s;
+  return s + ' '.repeat(n - s.length);
+}
+
+module.exports = { formatOutput, renderTable, pickTableKeys };

package/lib/path.js

@@ -0,0 +1,428 @@
+// lib/path.js — the path tokenizer + evaluator
+// Supports: dot access, bracket index, wildcard *, key filter [?(...)], slice [start:end]
+// Zero dependencies. Pure functions, fully testable.
+
+'use strict';
+
+/**
+ * Tokenize a path string into a list of segment descriptors.
+ * Grammar (informal):
+ *   ''            -> root (whole document)
+ *   .foo          -> object key 'foo'
+ *   ['foo']       -> object key 'foo' (bracket form, supports keys with dots/special chars)
+ *   [0]           -> array index 0
+ *   [-1]          -> array index from end (-1 = last)
+ *   [*]           -> wildcard: every element of an array / every value of an object
+ *   [1:3]         -> array slice from index 1 (inclusive) to 3 (exclusive)
+ *   [?(@.price > 10)]   -> filter: keep array elements where the expression is truthy
+ *   [?(@.active)]       -> filter: keep elements where the path is truthy
+ *   ..key        -> recursive descent: match 'key' at any depth
+ *
+ * Tokenizing is deliberately permissive but throws a clear ParseError on garbage.
+ */
+class ParseError extends Error {
+  constructor(message, position, source) {
+    super(`jpath parse error at position ${position}: ${message}${source ? ` (near: ...${source.slice(Math.max(0, position - 10), position + 10)}...)` : ''}`);
+    this.name = 'ParseError';
+    this.position = position;
+  }
+}
+
+// A segment is one of:
+//   { t: 'key',   k: 'foo' }
+//   { t: 'index', i: 0 }
+//   { t: 'wild' }
+//   { t: 'slice', start: 0, end: undefined, step: undefined }
+//   { t: 'filter', expr: 'tokenized-filter' }
+//   { t: 'desc', k: 'foo' }   // recursive descent for key 'foo'
+
+function tokenize(path) {
+  if (path == null) return [];
+  const s = String(path).trim();
+  const segs = [];
+  let i = 0;
+
+  // accept a leading '$' (root reference) or '@' as a no-op start
+  if (s[i] === '$') { i++; if (s[i] === '.' && s[i + 1] !== '.') i++; }
+  else if (s[i] === '@') { i++; }
+
+  while (i < s.length) {
+    if (s[i] === '.') {
+      // dot — could be recursive descent (..) or a single-child key
+      if (s[i + 1] === '.') {
+        // recursive descent: ..key
+        i += 2;
+        const key = readKey(s, i);
+        if (key.value === '' && key.consumed === 0) throw new ParseError('expected key after ".."', i, s);
+        i += key.consumed;
+        segs.push({ t: 'desc', k: key.value });
+      } else {
+        i++; // consume the dot
+        // Handle .* as wildcard (dot-wildcard syntax, e.g. $.store.*)
+        if (s[i] === '*') { segs.push({ t: 'wild' }); i++; continue; }
+        const key = readKey(s, i);
+        if (key.value === '' && key.consumed === 0) {
+          // trailing dot or dot before bracket — treat as no-op
+          continue;
+        }
+        i += key.consumed;
+        segs.push({ t: 'key', k: key.value });
+      }
+    } else if (s[i] === '[') {
+      const { seg, next } = readBracket(s, i);
+      segs.push(seg);
+      i = next;
+    } else {
+      // bare key not preceded by a dot (e.g. "foo" at start, or "foo.bar")
+      const key = readKey(s, i);
+      if (key.value === '' && key.consumed === 0) {
+        throw new ParseError(`unexpected character '${s[i]}'`, i, s);
+      }
+      i += key.consumed;
+      segs.push({ t: 'key', k: key.value });
+    }
+  }
+  return segs;
+}
+
+function readKey(s, i) {
+  // a key is a run of chars until a '.', '[', or end. Also supports single/double-quoted keys.
+  if (s[i] === '"' || s[i] === "'") {
+    const quote = s[i];
+    let j = i + 1;
+    let out = '';
+    while (j < s.length && s[j] !== quote) {
+      if (s[j] === '\\' && j + 1 < s.length) { out += s[j + 1]; j += 2; }
+      else { out += s[j]; j++; }
+    }
+    if (s[j] !== quote) throw new ParseError('unterminated quoted key', i, s);
+    return { value: out, consumed: (j + 1) - i };
+  }
+  let j = i;
+  let out = '';
+  while (j < s.length && s[j] !== '.' && s[j] !== '[') {
+    out += s[j];
+    j++;
+  }
+  return { value: out, consumed: j - i };
+}
+
+function readBracket(s, i) {
+  // s[i] === '['. Find matching ']' (naive — filters can contain brackets inside, so we track depth).
+  let depth = 1;
+  let j = i + 1;
+  while (j < s.length && depth > 0) {
+    if (s[j] === '[') depth++;
+    else if (s[j] === ']') depth--;
+    if (depth === 0) break;
+    j++;
+  }
+  if (depth !== 0) throw new ParseError('unterminated bracket', i, s);
+  const inner = s.slice(i + 1, j).trim();
+  const next = j + 1;
+  const seg = parseBracketInner(inner, i);
+  return { seg, next };
+}
+
+function parseBracketInner(inner, pos) {
+  if (inner === '*') return { t: 'wild' };
+
+  // slice: contains a ':' and starts/ends with digits / colons
+  if (/^-?\d*:-?\d*(:-?\d+)?$/.test(inner) && inner.includes(':')) {
+    const parts = inner.split(':');
+    const start = parts[0] === '' ? undefined : parseInt(parts[0], 10);
+    const end = parts[1] === '' ? undefined : parseInt(parts[1], 10);
+    const step = parts[2] !== undefined ? parseInt(parts[2], 10) : undefined;
+    return { t: 'slice', start, end, step };
+  }
+
+  // quoted string key: 'foo' or "foo"
+  if ((inner.startsWith("'") && inner.endsWith("'")) || (inner.startsWith('"') && inner.endsWith('"'))) {
+    return { t: 'key', k: inner.slice(1, -1) };
+  }
+
+  // filter: ?(...)
+  if (inner.startsWith('?')) {
+    const expr = inner.slice(1).trim();
+    // strip surrounding parens if the whole thing is wrapped
+    const e = expr.startsWith('(') && expr.endsWith(')') ? expr.slice(1, -1).trim() : expr;
+    return { t: 'filter', expr: e };
+  }
+
+  // plain integer index
+  if (/^-?\d+$/.test(inner)) {
+    return { t: 'index', i: parseInt(inner, 10) };
+  }
+
+  // fallback: treat as an unquoted key
+  return { t: 'key', k: inner };
+}
+
+// ---- evaluation ----
+
+function evalFilter(expr, item, root) {
+  // expr like: @.price > 10   |   @.tags contains 'red'   |   @.active   |   @.n in [1,2,3]
+  // We support a small, safe expression language. No eval(), ever.
+  const m = matchExpr(expr);
+  if (!m) throw new ParseError(`unsupported filter expression: ${expr}`, 0, expr);
+  const { left, op, right } = m;
+  const leftVal = resolveFilterRef(left, item, root);
+  const rightVal = resolveRight(right, item, root);
+
+  switch (op) {
+    case 'truthy': return isTruthy(leftVal);
+    case '!': return !isTruthy(leftVal);
+    case '==': return looseEq(leftVal, rightVal);
+    case '!=': return !looseEq(leftVal, rightVal);
+    case '>': return cmpNum(leftVal, rightVal) > 0;
+    case '>=': return cmpNum(leftVal, rightVal) >= 0;
+    case '<': return cmpNum(leftVal, rightVal) < 0;
+    case '<=': return cmpNum(leftVal, rightVal) <= 0;
+    case 'contains': return containsCheck(leftVal, rightVal);
+    case '!contains': return !containsCheck(leftVal, rightVal);
+    case 'in': return Array.isArray(rightVal) && rightVal.some((r) => looseEq(leftVal, r));
+    case '!in': return !(Array.isArray(rightVal) && rightVal.some((r) => looseEq(leftVal, r)));
+    case 'startsWith': return typeof leftVal === 'string' && String(rightVal).length > 0 && leftVal.startsWith(String(rightVal));
+    case 'endsWith': return typeof leftVal === 'string' && String(rightVal).length > 0 && leftVal.endsWith(String(rightVal));
+    case '=~': return typeof leftVal === 'string' && safeRegex(rightVal).test(leftVal);
+    default: throw new ParseError(`unknown operator ${op}`, 0, expr);
+  }
+}
+
+// match an expression into { left, op, right }
+function matchExpr(expr) {
+  // order matters — longest ops first
+  const ops = [
+    ['!contains', '!contains'],
+    ['contains', 'contains'],
+    ['startsWith', 'startsWith'],
+    ['endsWith', 'endsWith'],
+    ['!in', '!in'],
+    ['in', 'in'],
+    ['>=', '>='],
+    ['<=', '<='],
+    ['=~', '=~'],
+    ['==', '=='],
+    ['!=', '!='],
+    ['>', '>'],
+    ['<', '<'],
+  ];
+  for (const [sym, name] of ops) {
+    const idx = findOperator(expr, sym);
+    if (idx !== -1) {
+      return { left: expr.slice(0, idx).trim(), op: name, right: expr.slice(idx + sym.length).trim() };
+    }
+  }
+  // negation prefix
+  if (expr.startsWith('!')) return { left: expr.slice(1).trim(), op: '!', right: undefined };
+  return { left: expr.trim(), op: 'truthy', right: undefined };
+}
+
+// find an operator that is NOT inside a quoted string or bracket
+function findOperator(expr, sym) {
+  let depth = 0;
+  let inStr = false;
+  let strCh = '';
+  for (let i = 0; i <= expr.length - sym.length; i++) {
+    const c = expr[i];
+    if (inStr) {
+      if (c === strCh && expr[i - 1] !== '\\') inStr = false;
+      continue;
+    }
+    if (c === '"' || c === "'") { inStr = true; strCh = c; continue; }
+    if (c === '[' || c === '(') depth++;
+    else if (c === ']' || c === ')') depth--;
+    if (depth === 0 && expr.slice(i, i + sym.length) === sym) {
+      // avoid matching '=' inside '==' or '!=' for single-char '=' (not used here) and similar
+      return i;
+    }
+  }
+  return -1;
+}
+
+function resolveFilterRef(ref, item, root) {
+  // ref like '@.foo.bar' or '$.config.env' or a literal
+  if (ref === '@' || ref === '') return item;
+  if (ref.startsWith('@')) {
+    const p = ref.slice(1);
+    const segs = tokenize(p);
+    let cur = item;
+    for (const s of segs) {
+      const r = applySeg(s, cur, root);
+      cur = r;
+      if (cur === undefined) return undefined;
+    }
+    return cur;
+  }
+  if (ref.startsWith('$')) {
+    const p = ref.slice(1);
+    const segs = tokenize(p);
+    let cur = root;
+    for (const s of segs) {
+      cur = applySeg(s, cur, root);
+      if (cur === undefined) return undefined;
+    }
+    return cur;
+  }
+  return resolveLiteral(ref);
+}
+
+function resolveRight(ref, item, root) {
+  if (ref === undefined) return undefined;
+  if (ref.startsWith('[') && ref.endsWith(']')) {
+    // array literal
+    const inner = ref.slice(1, -1).trim();
+    if (inner === '') return [];
+    return inner.split(',').map((p) => {
+      const r = resolveRight(p.trim(), item, root);
+      return r;
+    });
+  }
+  if (ref.startsWith('@') || ref.startsWith('$')) return resolveFilterRef(ref, item, root);
+  return resolveLiteral(ref);
+}
+
+function resolveLiteral(s) {
+  if ((s.startsWith("'") && s.endsWith("'")) || (s.startsWith('"') && s.endsWith('"'))) {
+    return s.slice(1, -1).replace(/\\(.)/g, '$1');
+  }
+  if (s === 'true') return true;
+  if (s === 'false') return false;
+  if (s === 'null') return null;
+  if (/^-?\d+(\.\d+)?$/.test(s)) return Number(s);
+  // bareword treated as string for contains/startsWith style ops
+  return s;
+}
+
+function isTruthy(v) {
+  if (v == null) return false;
+  if (Array.isArray(v)) return v.length > 0;
+  if (typeof v === 'object') return Object.keys(v).length > 0;
+  if (typeof v === 'string') return v.length > 0;
+  if (typeof v === 'number') return v !== 0 && !Number.isNaN(v);
+  return Boolean(v);
+}
+
+function looseEq(a, b) {
+  if (a === b) return true;
+  if (a == null && b == null) return true;
+  if (typeof a === 'number' && typeof b === 'number') return a === b;
+  if (typeof a === 'string' && typeof b === 'string') return a === b;
+  if (typeof a === 'boolean' && typeof b === 'boolean') return a === b;
+  // loose: "10" == 10
+  return String(a) === String(b);
+}
+
+function cmpNum(a, b) {
+  if (typeof a !== 'number' || typeof b !== 'number') {
+    a = Number(a); b = Number(b);
+  }
+  if (Number.isNaN(a) || Number.isNaN(b)) return 0;
+  return a > b ? 1 : a < b ? -1 : 0;
+}
+
+function containsCheck(haystack, needle) {
+  if (typeof haystack === 'string') return haystack.includes(String(needle));
+  if (Array.isArray(haystack)) return haystack.some((h) => looseEq(h, needle));
+  if (haystack && typeof haystack === 'object') return Object.keys(haystack).some((k) => looseEq(k, needle));
+  return false;
+}
+
+function safeRegex(pattern) {
+  // pattern may be /foo/i or a bare string
+  let src = pattern;
+  let flags = '';
+  if (typeof pattern === 'string' && pattern.startsWith('/') && pattern.lastIndexOf('/') > 0) {
+    const lastSlash = pattern.lastIndexOf('/');
+    src = pattern.slice(1, lastSlash);
+    flags = pattern.slice(lastSlash + 1);
+  }
+  try { return new RegExp(src, flags); } catch { return { test: () => false }; }
+}
+
+// apply a single segment to a value. Returns the resolved value (may be array for wild/slice/desc).
+function applySeg(seg, val, root) {
+  switch (seg.t) {
+    case 'key':
+      if (val == null) return undefined;
+      if (Array.isArray(val)) return val.map((v) => (v && typeof v === 'object') ? v[seg.k] : undefined);
+      if (typeof val === 'object') return val[seg.k];
+      return undefined;
+
+    case 'index': {
+      if (!Array.isArray(val)) return undefined;
+      let idx = seg.i;
+      if (idx < 0) idx += val.length;
+      if (idx < 0 || idx >= val.length) return undefined;
+      return val[idx];
+    }
+
+    case 'wild': {
+      if (Array.isArray(val)) return val.slice(); // copy
+      if (val && typeof val === 'object') return Object.values(val);
+      return [];
+    }
+
+    case 'slice': {
+      if (!Array.isArray(val)) return [];
+      const len = val.length;
+      let start = seg.start == null ? 0 : (seg.start < 0 ? seg.start + len : seg.start);
+      let end = seg.end == null ? len : (seg.end < 0 ? seg.end + len : seg.end);
+      start = Math.max(0, Math.min(len, start));
+      end = Math.max(0, Math.min(len, end));
+      const step = seg.step || 1;
+      const out = [];
+      if (step > 0) for (let i = start; i < end; i += step) out.push(val[i]);
+      else for (let i = start; i > end; i += step) out.push(val[i]);
+      return out;
+    }
+
+    case 'filter': {
+      if (!Array.isArray(val)) {
+        // allow filtering a single object by wrapping
+        val = [val];
+      }
+      return val.filter((item) => {
+        try { return isTruthy(evalFilter(seg.expr, item, root)); }
+        catch { return false; }
+      });
+    }
+
+    case 'desc': {
+      // recursive descent: collect all values at any depth whose key === seg.k (for objects)
+      // or, when applied to an array, recurse into each element.
+      const results = [];
+      const walk = (node) => {
+        if (Array.isArray(node)) {
+          for (const el of node) walk(el);
+        } else if (node && typeof node === 'object') {
+          for (const [k, v] of Object.entries(node)) {
+            if (k === seg.k) results.push(v);
+            walk(v);
+          }
+        }
+      };
+      walk(val);
+      return results;
+    }
+
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * Evaluate a full path against a root document. Returns the matched value(s).
+ * Wildcards/filters naturally produce arrays; a single key/index returns the scalar.
+ */
+function evaluate(path, root) {
+  const segs = tokenize(path);
+  let cur = root;
+  for (const seg of segs) {
+    cur = applySeg(seg, cur, root);
+    if (cur === undefined) break;
+  }
+  return cur;
+}
+
+module.exports = { tokenize, evaluate, applySeg, evalFilter, ParseError };

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "jpath-cli",
+  "version": "0.1.0",
+  "description": "Query and extract data from JSON with a simple, powerful path syntax. A focused zero-dependency CLI — jq's little sibling for the 90% case.",
+  "license": "MIT",
+  "author": "takeaseatventure",
+  "keywords": [
+    "json",
+    "query",
+    "jq",
+    "path",
+    "extract",
+    "cli",
+    "filter",
+    "transform",
+    "jpath"
+  ],
+  "homepage": "https://github.com/takeaseatventure/jpath-cli#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/takeaseatventure/jpath-cli.git"
+  },
+  "bin": {
+    "jpath": "./bin/jpath.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "test/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "demo": "node bin/jpath.js --demo"
+  },
+  "bugs": {
+    "url": "https://github.com/takeaseatventure/jpath-cli/issues"
+  }
+}

package/test/path.test.js

@@ -0,0 +1,169 @@
+'use strict';
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const { tokenize, evaluate, evalFilter, ParseError } = require('../lib/path');
+const { formatOutput, renderTable } = require('../lib/format');
+
+const DOC = {
+  a: { b: { c: 42 } },
+  arr: [10, 20, 30],
+  users: [
+    { id: 1, name: 'Ada', age: 36, active: true, tags: ['rust', 'systems'] },
+    { id: 2, name: 'Grace', age: 28, active: true, tags: ['go', 'cloud'] },
+    { id: 3, name: 'Linus', age: 54, active: false, tags: ['c', 'kernel'] },
+  ],
+  'dotted.key': 'x',
+  nested: { deep: { id: 'deep-id' } },
+};
+
+// ---- tokenizer ----
+test('tokenize: dot path', () => {
+  assert.deepEqual(tokenize('.a.b.c'), [
+    { t: 'key', k: 'a' }, { t: 'key', k: 'b' }, { t: 'key', k: 'c' },
+  ]);
+});
+test('tokenize: leading $ is root no-op', () => {
+  assert.deepEqual(tokenize('$.a'), [{ t: 'key', k: 'a' }]);
+});
+test('tokenize: bracket index', () => {
+  assert.deepEqual(tokenize('arr[0]'), [{ t: 'key', k: 'arr' }, { t: 'index', i: 0 }]);
+});
+test('tokenize: bracket negative index', () => {
+  assert.deepEqual(tokenize('arr[-1]'), [{ t: 'key', k: 'arr' }, { t: 'index', i: -1 }]);
+});
+test('tokenize: wildcard', () => {
+  assert.deepEqual(tokenize('users[*]'), [{ t: 'key', k: 'users' }, { t: 'wild' }]);
+});
+test('tokenize: slice', () => {
+  assert.deepEqual(tokenize('arr[1:2]'), [{ t: 'key', k: 'arr' }, { t: 'slice', start: 1, end: 2, step: undefined }]);
+});
+test('tokenize: quoted key supports dots', () => {
+  assert.deepEqual(tokenize("['dotted.key']"), [{ t: 'key', k: 'dotted.key' }]);
+});
+test('tokenize: filter', () => {
+  const segs = tokenize('users[?(@.age > 30)]');
+  assert.equal(segs.length, 2);
+  assert.equal(segs[1].t, 'filter');
+  assert.equal(segs[1].expr, '@.age > 30');
+});
+test('tokenize: recursive descent', () => {
+  assert.deepEqual(tokenize('..id'), [{ t: 'desc', k: 'id' }]);
+});
+test('tokenize: empty path -> root', () => {
+  assert.deepEqual(tokenize(''), []);
+});
+test('tokenize: unterminated bracket throws', () => {
+  assert.throws(() => tokenize('arr[0'), ParseError);
+});
+
+// ---- evaluate: basic ----
+test('evaluate: dot access', () => {
+  assert.equal(evaluate('.a.b.c', DOC), 42);
+});
+test('evaluate: array index', () => {
+  assert.equal(evaluate('arr[0]', DOC), 10);
+});
+test('evaluate: negative index', () => {
+  assert.equal(evaluate('arr[-1]', DOC), 30);
+});
+test('evaluate: out of range index -> undefined', () => {
+  assert.equal(evaluate('arr[99]', DOC), undefined);
+});
+test('evaluate: missing key -> undefined', () => {
+  assert.equal(evaluate('.nope.nada', DOC), undefined);
+});
+
+// ---- evaluate: wildcards & slices ----
+test('evaluate: wildcard over array returns copy', () => {
+  assert.deepEqual(evaluate('arr[*]', DOC), [10, 20, 30]);
+});
+test('evaluate: slice returns subarray', () => {
+  assert.deepEqual(evaluate('arr[0:2]', DOC), [10, 20]);
+});
+test('evaluate: wildcard key on objects returns values', () => {
+  const r = evaluate('.a.b[*]', { a: { b: { x: 1, y: 2 } } });
+  assert.deepEqual(r.sort(), [1, 2]);
+});
+
+// ---- evaluate: filters ----
+test('evaluate: filter by numeric comparison', () => {
+  assert.deepEqual(evaluate('users[?(@.age > 30)].name', DOC), ['Ada', 'Linus']);
+});
+test('evaluate: filter by truthy', () => {
+  assert.deepEqual(evaluate('users[?(@.active)].name', DOC), ['Ada', 'Grace']);
+});
+test('evaluate: filter negation', () => {
+  assert.deepEqual(evaluate('users[?(!@.active)].name', DOC), ['Linus']);
+});
+test('evaluate: filter contains (array)', () => {
+  assert.deepEqual(evaluate("users[?(@.tags contains 'go')].name", DOC), ['Grace']);
+});
+test('evaluate: filter equality', () => {
+  assert.deepEqual(evaluate("users[?(@.name == 'Ada')].age", DOC), [36]);
+});
+test('evaluate: filter regex', () => {
+  assert.deepEqual(evaluate("users[?(@.name =~ /^A/)].name", DOC), ['Ada']);
+});
+test('evaluate: filter in', () => {
+  assert.deepEqual(evaluate('users[?(@.age in [28,54])].name', DOC), ['Grace', 'Linus']);
+});
+
+// ---- evaluate: recursive descent ----
+test('evaluate: recursive descent collects all matching keys', () => {
+  const r = evaluate('..id', DOC);
+  assert.deepEqual(r.sort(), [1, 2, 3, 'deep-id']);
+});
+
+// ---- evaluate: edge cases ----
+test('evaluate: root path returns whole doc', () => {
+  assert.equal(evaluate('', DOC), DOC);
+});
+test('evaluate: quoted dotted key', () => {
+  assert.equal(evaluate("['dotted.key']", DOC), 'x');
+});
+
+// ---- evalFilter unit ----
+test('evalFilter: loose equality string/number', () => {
+  assert.equal(evalFilter("@.n == '5'", { n: 5 }, {}), true);
+});
+
+// ---- formatters ----
+test('format: json pretty', () => {
+  assert.equal(formatOutput({ a: 1 }, 'json'), '{\n  "a": 1\n}');
+});
+test('format: compact', () => {
+  assert.equal(formatOutput({ a: 1 }, 'compact'), '{"a":1}');
+});
+test('format: jsonl', () => {
+  assert.equal(formatOutput([1, 2, 3], 'jsonl'), '1\n2\n3');
+});
+test('format: raw string unwrapped', () => {
+  assert.equal(formatOutput('hello', 'raw'), 'hello');
+});
+test('format: count', () => {
+  assert.equal(formatOutput([1, 2, 3], 'count'), '3');
+});
+test('format: keys', () => {
+  assert.equal(formatOutput({ a: 1, b: 2 }, 'keys'), 'a\nb');
+});
+test('format: table renders header + rows', () => {
+  const out = formatOutput([{ id: 1, name: 'Ada' }, { id: 2, name: 'Bo' }], 'table');
+  const lines = out.split('\n');
+  assert.ok(lines[0].includes('id'));
+  assert.ok(lines[0].includes('name'));
+  assert.ok(lines[2].includes('Ada'));
+  assert.ok(lines[3].includes('Bo'));
+});
+test('format: unknown format throws', () => {
+  assert.throws(() => formatOutput({}, 'xml'));
+});
+
+// ---- renderTable edge cases ----
+test('renderTable: empty array', () => {
+  assert.equal(renderTable([]), '(empty)');
+});
+test('renderTable: scalar array', () => {
+  assert.equal(renderTable([1, 2, 3]), '1\n2\n3');
+});
+
+console.log('All jpath unit tests registered.');