@shukelabs/jq 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SHUKE LABS
+
+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,53 @@
+# @shukelabs/jq
+
+The `jq` command for machines where the only thing you can install is an npm package.
+
+```bash
+npm install -g @shukelabs/jq
+jq --version   # jq-1.8.2
+```
+
+## What this is, and what it is not
+
+This is **not** a replacement for [jq](https://github.com/jqlang/jq), and not a fork or a
+reimplementation of it. If you can install jq the normal way (`apt`, `brew`, `winget`, `scoop`,
+or the [official release binaries](https://github.com/jqlang/jq/releases)), do that. Native jq
+is faster and has none of the limitations below.
+
+It exists for one situation: a locked-down machine where native executables cannot be
+downloaded or installed, but Node.js and an npm registry are available. There, tools and
+scripts that call `jq` can still work.
+
+The actual jq is the official jq source compiled to WebAssembly by
+[jq-wasm](https://github.com/owenthereal/jq-wasm). This package adds a small command-line
+wrapper (`bin/jq.mjs`) that turns `jq [options] filter [files...]` into a jq-wasm call. It ships
+no native binary and runs no install scripts.
+
+## Differences from native jq
+
+jq runs inside a WebAssembly sandbox. The wrapper bridges what it can and refuses what it cannot,
+rather than produce a silently different result:
+
+| Feature | Behaviour |
+| --- | --- |
+| Input files, `-f`, `--slurpfile`, `--rawfile` | Supported. The wrapper reads the files and hands their contents to jq. |
+| `--args`, `--jsonargs`, `-L` / modules | Rejected with exit code 2. |
+| Streaming input | Not supported: nothing is printed until stdin reaches end of file, so `tail -f log \| jq` does not work. |
+| `-n` | Input is read only when the filter mentions `input` or `inputs`; a stray `"input"` inside a string literal also counts. |
+| `$ENV`, `env` | See the sandbox environment, not your shell's. |
+| `localtime`, `strflocaltime` | Use UTC. |
+| `input_filename` | Always `null`. |
+| `-C` (color) | Ignored; output is never colored. |
+| Line endings | Always LF, also on Windows (native Windows jq writes CRLF). |
+| Startup | About 0.3 s per call (Node.js start-up), against about 0.1 s for native jq. |
+
+Apart from these, the test suite checks that output and exit codes match native jq. CI runs that
+comparison against the runner's own jq on every push.
+
+## Requirements
+
+Node.js 20 or later.
+
+## Licence
+
+MIT. jq and jq-wasm are also MIT-licensed; see their repositories.

package/bin/jq.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+// jq command line over jq-wasm: the official jq compiled to WebAssembly.
+// jq runs in a sandbox that cannot see host files, so this wrapper reads
+// every file the command line names and hands jq the contents instead.
+import { readFileSync } from "node:fs";
+import { loadJq } from "jq-wasm";
+
+const jq = await loadJq();
+
+// jq-wasm trims leading and trailing whitespace from jq's output. The real
+// jq CLI never does, and `-r`/`-j` output can legitimately start or end with
+// spaces or blank lines, so neutralise the trim for the duration of the call.
+function run(input, query, opts) {
+  const trim = String.prototype.trim;
+  String.prototype.trim = function () { return String(this); };
+  try {
+    return jq.raw(input, query, opts);
+  } finally {
+    String.prototype.trim = trim;
+  }
+}
+
+function usage(msg) {
+  process.stderr.write(`jq: error: ${msg}\nUse jq --help for help with command-line options.\n`);
+  process.exit(2);
+}
+
+function read(file) {
+  try {
+    return readFileSync(file === "-" ? 0 : file, "utf8");
+  } catch (e) {
+    process.stderr.write(`jq: error: Could not open ${file}: ${e.code === "ENOENT" ? "No such file or directory" : e.message}\n`);
+    process.exit(2);
+  }
+}
+
+// Options that take values, by how many. Every other option is a switch.
+const VALUES = { "--arg": 2, "--argjson": 2, "--slurpfile": 2, "--rawfile": 2, "--indent": 1 };
+const UNSUPPORTED = new Set(["--args", "--jsonargs", "-L", "--library-path"]);
+const NO_INPUT = new Set(["--version", "-V", "-h", "--help", "--build-configuration"]);
+
+const argv = process.argv.slice(2);
+const opts = [], positionals = [], switches = new Set();
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  if (a === "--") { positionals.push(...argv.slice(i + 1)); break; }
+  if (a === "-" || !a.startsWith("-")) { positionals.push(a); continue; }
+  // A bundle (-nrf) is its short options, in order.
+  const names = /^-[a-zA-Z]{2,}$/.test(a) ? [...a.slice(1)].map((c) => "-" + c) : [a];
+  for (const name of names) {
+    if (UNSUPPORTED.has(name) || name.startsWith("--library-path=")) usage(`${name} is not supported by @shukelabs/jq`);
+    const n = VALUES[name] ?? 0;
+    if (i + n >= argv.length) usage(`${name} takes ${n} parameter${n > 1 ? "s" : ""}`);
+    const v = argv.slice(i + 1, i + 1 + n);
+    i += n;
+    if (name === "-f" || name === "--from-file") switches.add("-f");
+    else if (name === "--rawfile") opts.push("--argjson", v[0], JSON.stringify(read(v[1])));
+    else if (name === "--slurpfile") {
+      const r = run(read(v[1]), ".", ["-c", "-s"]);
+      if (r.exitCode !== 0) { process.stderr.write(r.stderr); process.exit(2); }
+      opts.push("--argjson", v[0], r.stdout);
+    } else {
+      opts.push(name, ...v);
+      if (n === 0) switches.add(name);
+    }
+  }
+}
+
+// The first positional is the filter, or with -f the file holding it.
+let filter = positionals.shift();
+if (switches.has("-f") && filter !== undefined) filter = read(filter);
+const files = positionals;
+const noInput = [...NO_INPUT].some((s) => switches.has(s));
+if (filter === undefined && !noInput) {
+  // Like jq: default to "." unless both ends are a terminal.
+  if (process.stdin.isTTY && process.stdout.isTTY) usage("no filter given");
+  filter = ".";
+}
+
+// Under -n jq reads input only when the filter calls input/inputs. Skipping
+// the read otherwise matters: jq never opens the files then, and reading an
+// open-but-idle stdin would hang.
+const nullInput = switches.has("-n") || switches.has("--null-input");
+const wantsInput = !noInput && (!nullInput || /(?<![.$\w])inputs?\b(?!\s*:)/.test(filter ?? ""));
+// jq reads its input files as one continuous stream, so join them as-is.
+const input = !wantsInput ? "" : files.length ? files.map(read).join("") : read("-");
+const r = run(input, filter ?? ".", opts);
+process.stdout.write(r.stdout);
+process.stderr.write(r.stderr);
+process.exitCode = r.exitCode;

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@shukelabs/jq",
+  "version": "1.0.0",
+  "description": "The jq command for machines that can only install npm packages: official jq compiled to WebAssembly (via jq-wasm), no native binary.",
+  "keywords": ["jq", "json", "cli", "wasm", "webassembly"],
+  "license": "MIT",
+  "author": "shukebeta <weizhong2004@gmail.com>",
+  "homepage": "https://github.com/SHUKE-LABS/jq#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SHUKE-LABS/jq.git"
+  },
+  "bugs": "https://github.com/SHUKE-LABS/jq/issues",
+  "type": "module",
+  "bin": {
+    "jq": "bin/jq.mjs"
+  },
+  "files": [
+    "bin"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "dependencies": {
+    "jq-wasm": "3.0.0-jq-1.8.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}