@lovrabet/cli-framework 1.0.1 → 1.0.3

package/lib/framework/output.d.ts

@@ -6,10 +6,12 @@
  * - `compress` — Single-line JSON envelope (default).
  * - `pretty`  — Human-readable plain-text layout.
  *
- * Supports `--jq` post-filtering in `json` / `compress` modes via the
- * bundled `node-jq` executable (or a `jq` binary on PATH).
+ * Supports `--jq` post-filtering in `json` / `compress` modes via a jq binary
+ * resolved from `JQ_PATH` or the system `PATH`.
  */
 import type { CommandResult, OutputFormat, Risk } from "./types.js";
+import { type JqBinaryResolverOptions } from "../utils/apply-jq-filter.js";
+import { type CliErrorsShape } from "../errors.js";
 /** Shared options passed through every internal print function. */
 interface OutputOptions {
     /** Full command label (e.g. `"api list"`). */
@@ -23,6 +25,15 @@ interface OutputOptions {
     /** Optional jq expression for post-filtering (json/compress modes only). */
     jqFilter?: string;
 }
+/**
+ * Options for constructing a CLI-specific output formatter.
+ */
+export interface CreateFormatOutputOptions {
+    /** Error factory used when jq execution fails. */
+    cliErrors?: Pick<CliErrorsShape, "validation">;
+    /** jq binary resolution strategy for this concrete CLI. */
+    jqBinaryResolverOptions?: JqBinaryResolverOptions;
+}
 /**
  * Central formatting entry point used by the runner adapter.
  *
@@ -41,5 +52,7 @@ interface OutputOptions {
  * formatOutput({ ok: true, data: { id: 1 } }, { command: "app list", risk: "read", format: "compress" });
  * ```
  */
-export declare function formatOutput<T>(result: CommandResult<T>, options: OutputOptions): void;
+export declare function createFormatOutput(options?: CreateFormatOutputOptions): <T>(result: CommandResult<T>, outputOptions: OutputOptions) => void;
+/** Default framework formatter using `JQ_PATH` / `PATH` resolution only. */
+export declare const formatOutput: <T>(result: CommandResult<T>, outputOptions: OutputOptions) => void;
 export {};

package/lib/framework/output.js

@@ -6,18 +6,18 @@
  * - `compress` — Single-line JSON envelope (default).
  * - `pretty`  — Human-readable plain-text layout.
  *
- * Supports `--jq` post-filtering in `json` / `compress` modes via the
- * bundled `node-jq` executable (or a `jq` binary on PATH).
+ * Supports `--jq` post-filtering in `json` / `compress` modes via a jq binary
+ * resolved from `JQ_PATH` or the system `PATH`.
  */
 import chalk from "chalk";
 import { createJqFilter } from "../utils/apply-jq-filter.js";
 import { createCliErrors } from "../errors.js";
-const applyJqFilter = createJqFilter(createCliErrors({
+const DEFAULT_CLI_ERRORS = createCliErrors({
     cliBinName: "cli",
     authRequiredHint: "",
     configMissingHint: "",
     notInProjectHint: "",
-}));
+});
 /**
  * Central formatting entry point used by the runner adapter.
  *
@@ -36,20 +36,25 @@ const applyJqFilter = createJqFilter(createCliErrors({
  * formatOutput({ ok: true, data: { id: 1 } }, { command: "app list", risk: "read", format: "compress" });
  * ```
  */
-export function formatOutput(result, options) {
-    switch (options.format) {
-        case "json":
-            printJson(result, options);
-            break;
-        case "compress":
-            printCompress(result, options);
-            break;
-        case "pretty":
-        default:
-            printPretty(result, options);
-            break;
-    }
+export function createFormatOutput(options = {}) {
+    const applyJqFilter = createJqFilter(options.cliErrors ?? DEFAULT_CLI_ERRORS, options.jqBinaryResolverOptions);
+    return function formatOutput(result, outputOptions) {
+        switch (outputOptions.format) {
+            case "json":
+                printJson(result, outputOptions, applyJqFilter);
+                break;
+            case "compress":
+                printCompress(result, outputOptions, applyJqFilter);
+                break;
+            case "pretty":
+            default:
+                printPretty(result, outputOptions);
+                break;
+        }
+    };
 }
+/** Default framework formatter using `JQ_PATH` / `PATH` resolution only. */
+export const formatOutput = createFormatOutput();
 /**
  * Wraps the command result in an {@link OutputEnvelope} by merging the
  * command metadata from `options` and the result data / error.
@@ -81,8 +86,8 @@ function buildEnvelope(result, options) {
  * @param result  - The command result to serialize.
  * @param options - Output options including jq filter.
  */
-function printJson(result, options) {
-    writeJsonWithOptionalJq(`${JSON.stringify(buildEnvelope(result, options), null, 2)}\n`, options);
+function printJson(result, options, applyJqFilter) {
+    writeJsonWithOptionalJq(`${JSON.stringify(buildEnvelope(result, options), null, 2)}\n`, options, applyJqFilter);
 }
 /**
  * Formats and prints the result as single-line (compact) JSON.
@@ -91,8 +96,8 @@ function printJson(result, options) {
  * @param result  - The command result to serialize.
  * @param options - Output options including jq filter.
  */
-function printCompress(result, options) {
-    writeJsonWithOptionalJq(`${JSON.stringify(buildEnvelope(result, options))}\n`, options);
+function printCompress(result, options, applyJqFilter) {
+    writeJsonWithOptionalJq(`${JSON.stringify(buildEnvelope(result, options))}\n`, options, applyJqFilter);
 }
 /**
  * Writes a JSON string to stdout, optionally piping it through `jq`.
@@ -100,7 +105,7 @@ function printCompress(result, options) {
  * @param jsonLine - Complete JSON line (must end with `\n`).
  * @param options  - Output options carrying the jq expression.
  */
-function writeJsonWithOptionalJq(jsonLine, options) {
+function writeJsonWithOptionalJq(jsonLine, options, applyJqFilter) {
     const expr = options.jqFilter?.trim();
     if (!expr) {
         process.stdout.write(jsonLine);

package/lib/index.d.ts

@@ -205,5 +205,12 @@ Paging,
  * @description List response wrapper with records and optional paging.
  */
 ListResponse, } from "./framework/response.js";
-export { formatOutput } from "./framework/output.js";
+export { createFormatOutput, formatOutput } from "./framework/output.js";
+export type { 
+/**
+ * @see ./framework/output.ts
+ * @description Options for constructing a CLI-specific output formatter.
+ */
+CreateFormatOutputOptions, } from "./framework/output.js";
+export { resolveBundledJqPaths } from "./utils/jq-sidecar.js";
 export { createJqFilter } from "./utils/apply-jq-filter.js";

package/lib/index.js

@@ -47,6 +47,8 @@ extractList,
 /** @see ./framework/response.ts */
 extractPaging, } from "./framework/response.js";
 // ─── Output Formatting ─────────────────────────────────────────────────────────
-export { formatOutput } from "./framework/output.js";
+export { createFormatOutput, formatOutput } from "./framework/output.js";
+// ─── Bundled jq Sidecar ────────────────────────────────────────────────────────
+export { resolveBundledJqPaths } from "./utils/jq-sidecar.js";
 // ─── JQ Filter ────────────────────────────────────────────────────────────────
 export { createJqFilter } from "./utils/apply-jq-filter.js";

package/lib/utils/apply-jq-filter.d.ts

@@ -7,12 +7,66 @@
  * or `--format compress`.
  *
  * The jq binary is resolved in this order:
- * 1. Bundled `jq` shipped with the `node-jq` npm package (platform-specific).
- * 2. A `jq` executable found on `PATH`.
+ * 1. `JQ_PATH` when explicitly provided.
+ * 2. An optional bundled jq candidate path injected by the host CLI.
+ * 3. A `jq` executable found on `PATH`.
  *
  * @module apply-jq-filter
  */
 import type { CliErrorsShape } from "../errors.js";
+/** Source used to resolve the jq binary. */
+export type JqBinarySource = "env" | "bundled" | "path";
+/**
+ * Options controlling how a jq executable is discovered.
+ */
+export interface JqBinaryResolverOptions {
+    /**
+     * Explicit bundled jq candidates supplied by the host CLI.
+     *
+     * The first existing path wins.
+     */
+    bundledJqPaths?: readonly string[];
+    /**
+     * Environment map used for resolution.
+     *
+     * Defaults to `process.env`; exposed for tests.
+     */
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Result returned by jq binary resolution.
+ */
+export interface ResolvedJqBinary {
+    /** Command or absolute file path passed to `execFileSync`. */
+    command: string;
+    /** Resolution source used for the command. */
+    source: JqBinarySource;
+}
+/**
+ * Thrown when `JQ_PATH` is present but does not point to an existing file.
+ */
+export declare class JqBinaryResolutionError extends Error {
+    readonly jqPath: string;
+    /** Stable machine-readable error code. */
+    code: string;
+    /**
+     * @param jqPath - Invalid path supplied through `JQ_PATH`.
+     */
+    constructor(jqPath: string);
+}
+/**
+ * Resolves the jq executable for the current process.
+ *
+ * Resolution order:
+ * 1. `JQ_PATH`
+ * 2. injected bundled jq candidates
+ * 3. `jq` on `PATH`
+ *
+ * @param options - Resolution options including env overrides and bundled paths.
+ * @returns The command/path to execute and its source.
+ * @throws {@link JqBinaryResolutionError} if `JQ_PATH` is set but missing.
+ */
+export declare function resolveJqBinary(options?: JqBinaryResolverOptions): ResolvedJqBinary;
 /**
  * Creates a jq filter function bound to a specific error factory.
  *
@@ -21,6 +75,7 @@ import type { CliErrorsShape } from "../errors.js";
  * throws a typed {@link CliError} with code `"validation_error"`.
  *
  * @param cliErrors - Error factory providing `validation` for error reporting.
+ * @param options - Optional jq binary resolution customizations.
  * @returns An `applyJqFilter(jsonInput, expr)` function.
  *
  * @example
@@ -30,4 +85,4 @@ import type { CliErrorsShape } from "../errors.js";
  * // filtered === "1\n"
  * ```
  */
-export declare function createJqFilter(cliErrors: Pick<CliErrorsShape, "validation">): (jsonInput: string, expr: string) => string;
+export declare function createJqFilter(cliErrors: Pick<CliErrorsShape, "validation">, options?: JqBinaryResolverOptions): (jsonInput: string, expr: string) => string;

package/lib/utils/apply-jq-filter.js

@@ -7,17 +7,62 @@
  * or `--format compress`.
  *
  * The jq binary is resolved in this order:
- * 1. Bundled `jq` shipped with the `node-jq` npm package (platform-specific).
- * 2. A `jq` executable found on `PATH`.
+ * 1. `JQ_PATH` when explicitly provided.
+ * 2. An optional bundled jq candidate path injected by the host CLI.
+ * 3. A `jq` executable found on `PATH`.
  *
  * @module apply-jq-filter
  */
 import { execFileSync } from "node:child_process";
 import { existsSync } from "node:fs";
-import { createRequire } from "node:module";
-import path from "node:path";
 /** Maximum stdout buffer for the jq process (50 MB). */
 const MAX_BUFFER = 50 * 1024 * 1024;
+/** Error code used when `JQ_PATH` points to a missing executable. */
+const INVALID_JQ_PATH_CODE = "jq_path_invalid";
+/**
+ * Thrown when `JQ_PATH` is present but does not point to an existing file.
+ */
+export class JqBinaryResolutionError extends Error {
+    jqPath;
+    /** Stable machine-readable error code. */
+    code = INVALID_JQ_PATH_CODE;
+    /**
+     * @param jqPath - Invalid path supplied through `JQ_PATH`.
+     */
+    constructor(jqPath) {
+        super(`JQ_PATH points to a missing jq executable: ${jqPath}`);
+        this.jqPath = jqPath;
+        this.name = "JqBinaryResolutionError";
+    }
+}
+/**
+ * Resolves the jq executable for the current process.
+ *
+ * Resolution order:
+ * 1. `JQ_PATH`
+ * 2. injected bundled jq candidates
+ * 3. `jq` on `PATH`
+ *
+ * @param options - Resolution options including env overrides and bundled paths.
+ * @returns The command/path to execute and its source.
+ * @throws {@link JqBinaryResolutionError} if `JQ_PATH` is set but missing.
+ */
+export function resolveJqBinary(options = {}) {
+    const env = options.env ?? process.env;
+    const jqPath = readJqPath(env);
+    if (jqPath) {
+        if (!existsSync(jqPath)) {
+            throw new JqBinaryResolutionError(jqPath);
+        }
+        return { command: jqPath, source: "env" };
+    }
+    for (const candidate of options.bundledJqPaths ?? []) {
+        if (candidate && existsSync(candidate)) {
+            return { command: candidate, source: "bundled" };
+        }
+    }
+    return { command: "jq", source: "path" };
+}
 /**
  * Creates a jq filter function bound to a specific error factory.
  *
@@ -26,6 +71,7 @@ const MAX_BUFFER = 50 * 1024 * 1024;
  * throws a typed {@link CliError} with code `"validation_error"`.
  *
  * @param cliErrors - Error factory providing `validation` for error reporting.
+ * @param options - Optional jq binary resolution customizations.
  * @returns An `applyJqFilter(jsonInput, expr)` function.
  *
  * @example
@@ -35,7 +81,7 @@ const MAX_BUFFER = 50 * 1024 * 1024;
  * // filtered === "1\n"
  * ```
  */
-export function createJqFilter(cliErrors) {
+export function createJqFilter(cliErrors, options = {}) {
     /**
      * Applies a jq expression filter to a JSON input string.
      *
@@ -48,7 +94,17 @@ export function createJqFilter(cliErrors) {
      *          - The input is not valid JSON.
      */
     return function applyJqFilter(jsonInput, expr) {
-        const jqCmd = resolveJqBinary();
+        const env = options.env ?? process.env;
+        let jqCmd = "jq";
+        try {
+            jqCmd = resolveJqBinary(options).command;
+        }
+        catch (err) {
+            if (err instanceof JqBinaryResolutionError) {
+                throw cliErrors.validation(err.message, "Point JQ_PATH to a valid jq executable, unset it, or rely on the bundled/system jq.");
+            }
+            throw err;
+        }
         try {
             return execFileSync(jqCmd, [expr], {
                 input: jsonInput,
@@ -59,11 +115,11 @@ export function createJqFilter(cliErrors) {
         }
         catch (err) {
             const e = err;
-            // jq binary not found
             if (e.code === "ENOENT") {
-                throw cliErrors.validation("--jq needs a jq binary. Bundled path (from node-jq) was not found and `jq` is not on PATH. " +
-                    "Reinstall dependencies (allow install scripts), set JQ_PATH to a jq executable, " +
-                    "or install jq: https://jqlang.org/", "e.g. `brew install jq` — or `npm install` with scripts enabled so node-jq can download jq");
+                throw cliErrors.validation(`--jq needs a jq binary. Checked ${describeResolutionTargets(env, options.bundledJqPaths)}.`, describeMissingBinaryHint(options.bundledJqPaths));
+            }
+            if (e.code === "EACCES") {
+                throw cliErrors.validation(`jq binary is not executable: ${jqCmd}`, "Fix the file permissions, point JQ_PATH to an executable jq binary, or install jq on PATH.");
             }
             const stderr = e.stderr?.toString?.().trim() ?? "";
             const fallback = (e.message ?? String(err)).trim();
@@ -74,26 +130,48 @@ export function createJqFilter(cliErrors) {
     };
 }
 /**
- * Resolves the path to the jq executable.
+ * Reads a normalized `JQ_PATH` value from the provided environment.
  *
- * Resolution order:
- * 1. Bundled `jq` from the `node-jq` npm package (platform-specific binary).
- * 2. `jq` / `jq.exe` found on `PATH` via the `which` equivalent.
+ * @param env - Environment variables to inspect.
+ * @returns Trimmed `JQ_PATH` when set; otherwise `undefined`.
+ */
+function readJqPath(env) {
+    const raw = env.JQ_PATH;
+    if (typeof raw !== "string")
+        return undefined;
+    const trimmed = raw.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+/**
+ * Builds a user-facing description of the jq binary search order.
  *
- * @returns Absolute path to the jq executable.
+ * @param env - Environment variables used for this resolution.
+ * @param bundledJqPaths - Bundled jq candidates supplied by the host CLI.
+ * @returns Human-readable search target description.
  */
-function resolveJqBinary() {
-    try {
-        const require = createRequire(import.meta.url);
-        const pkgDir = path.dirname(require.resolve("node-jq/package.json"));
-        const binDir = path.join(pkgDir, "bin");
-        const name = process.platform === "win32" ? "jq.exe" : "jq";
-        const bundled = path.join(binDir, name);
-        if (existsSync(bundled))
-            return bundled;
+function describeResolutionTargets(env, bundledJqPaths) {
+    const targets = ["`jq` on PATH"];
+    if ((bundledJqPaths?.length ?? 0) > 0) {
+        targets.unshift("the bundled jq shipped with this CLI");
     }
-    catch {
-        // node-jq not installed or resolution failed — fall through to PATH
+    if (!readJqPath(env)) {
+        targets.unshift("`JQ_PATH`");
+    }
+    if (targets.length === 1)
+        return targets[0] ?? "`jq` on PATH";
+    if (targets.length === 2)
+        return `${targets[0]} and ${targets[1]}`;
+    return `${targets.slice(0, -1).join(", ")}, and ${targets.at(-1)}`;
+}
+/**
+ * Builds the remediation hint shown when jq cannot be found.
+ *
+ * @param bundledJqPaths - Bundled jq candidates supplied by the host CLI.
+ * @returns Human-readable remediation hint.
+ */
+function describeMissingBinaryHint(bundledJqPaths) {
+    if ((bundledJqPaths?.length ?? 0) > 0) {
+        return "Set JQ_PATH to a valid jq executable, reinstall the CLI if its bundled jq is missing, or install jq on PATH.";
     }
-    return "jq";
+    return "Set JQ_PATH to a valid jq executable or install jq on PATH.";
 }

package/lib/utils/jq-sidecar.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Resolves bundled jq candidate paths for the current runtime platform.
+ *
+ * The result is ordered from most preferred to least preferred. Callers should
+ * test the paths in order and use the first one that exists.
+ *
+ * @param platform - Node.js platform, defaults to `process.platform`.
+ * @param arch - Node.js architecture, defaults to `process.arch`.
+ * @returns Candidate absolute paths to bundled jq executables.
+ */
+export declare function resolveBundledJqPaths(platform?: NodeJS.Platform, arch?: NodeJS.Architecture): string[];

package/lib/utils/jq-sidecar.js

@@ -0,0 +1,28 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+/** Supported bundled jq targets keyed by `platform:arch`. */
+const JQ_TARGETS = {
+    "darwin:arm64": ["darwin-arm64", "darwin-x64"],
+    "darwin:x64": ["darwin-x64"],
+    "linux:arm64": ["linux-arm64"],
+    "linux:x64": ["linux-x64"],
+    "win32:arm64": ["win32-x64"],
+    "win32:x64": ["win32-x64"],
+};
+const CURRENT_FILE = fileURLToPath(import.meta.url);
+const PACKAGE_ROOT = path.resolve(path.dirname(CURRENT_FILE), "../..");
+const SIDECAR_ROOT = path.join(PACKAGE_ROOT, "sidecar", "jq");
+/**
+ * Resolves bundled jq candidate paths for the current runtime platform.
+ *
+ * The result is ordered from most preferred to least preferred. Callers should
+ * test the paths in order and use the first one that exists.
+ *
+ * @param platform - Node.js platform, defaults to `process.platform`.
+ * @param arch - Node.js architecture, defaults to `process.arch`.
+ * @returns Candidate absolute paths to bundled jq executables.
+ */
+export function resolveBundledJqPaths(platform = process.platform, arch = process.arch) {
+    const targetDirs = JQ_TARGETS[`${platform}:${arch}`] ?? [];
+    return targetDirs.map((dir) => path.join(SIDECAR_ROOT, dir, platform === "win32" ? "jq.exe" : "jq"));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lovrabet/cli-framework",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -11,25 +11,26 @@
     }
   },
   "files": [
-    "lib"
+    "lib",
+    "sidecar"
   ],
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
     "build": "rm -rf lib && tsc && echo 'cli-framework build done'",
+    "update:jq-sidecar": "node scripts/update-jq-sidecar.mjs",
     "beta-release": "sh scripts/update-beta-version.sh && bun run build && git push && git push origin --tag && bun publish --tag beta",
     "release": "sh scripts/update-latest-version.sh && bun run build && git push && git push origin --tag && bun publish",
     "typecheck": "tsc --noEmit",
     "test": "vitest run"
   },
   "dependencies": {
-    "chalk": "^5.6.2",
-    "node-jq": "^6.3.1"
+    "chalk": "^5.6.2"
   },
   "devDependencies": {
     "@types/node": "^24.5.2",
-    "typescript": "latest",
+    "typescript": "5.9.3",
     "vitest": "^4.1.2"
   }
-}
+}

package/sidecar/jq/README.md

@@ -0,0 +1,24 @@
+This directory vendors jq binaries that ship with `@lovrabet/cli-framework`.
+
+Consumer CLIs such as `@lovrabet/rabetbase-cli` and `@lovrabet/lovrabet-cli`
+resolve these binaries through the framework package.
+
+- Upstream project: `jqlang/jq`
+- Version: `jq-1.8.1`
+- License: `MIT`
+- Release source: `https://github.com/jqlang/jq/releases/tag/jq-1.8.1`
+
+Bundled targets:
+
+- `darwin-arm64/jq`
+- `darwin-x64/jq`
+- `linux-arm64/jq`
+- `linux-x64/jq`
+- `win32-x64/jq.exe`
+
+Update policy:
+
+1. Download binaries only from the official jq release assets.
+2. Keep file names stable (`jq` / `jq.exe`) so runtime resolution stays simple.
+3. Refresh the sidecar with `npm run update:jq-sidecar -- jq-<version>` when the bundled jq version changes.
+4. Update this README when the bundled jq version changes.