@lovrabet/cli-framework 0.1.1-beta.0

package/lib/framework/types.js

@@ -0,0 +1,53 @@
+/**
+ * @fileoverview Core domain types for the CLI framework.
+ *
+ * Defines the primitive risk levels, output formats, and the central
+ * {@link CommandDefinition} interface that every declarative command must implement.
+ */
+/**
+ * Returns a numeric ordering value for a given risk level.
+ * Higher numbers indicate greater risk. Used by {@link assertRiskWithinLevel}
+ * to compare the command's risk against the configured risk ceiling.
+ *
+ * @param risk - A `Risk` value, an arbitrary string, or `undefined`.
+ * @returns `0` for `read`, `1` for `write`, `2` for `high-risk-write`, or `0` as fallback.
+ *
+ * @example
+ * ```ts
+ * riskLevelOrder("high-risk-write") > riskLevelOrder("read") // true
+ * ```
+ */
+export function riskLevelOrder(risk) {
+    const order = { read: 0, write: 1, "high-risk-write": 2 };
+    return order[risk ?? "read"] ?? 0;
+}
+/**
+ * Type guard that checks whether a value is a valid {@link OutputFormat}.
+ *
+ * @param v - Any value to test.
+ * @returns `true` if `v` is `"json"`, `"pretty"`, or `"compress"`.
+ */
+export function isValidFormat(v) {
+    return v === "json" || v === "pretty" || v === "compress";
+}
+/**
+ * Converts legacy or alternative format aliases to the canonical {@link OutputFormat}.
+ * The legacy alias `"table"` maps to `"pretty"`.
+ *
+ * @param v - Any value to normalize.
+ * @returns The canonical `OutputFormat`, or `undefined` if `v` cannot be mapped.
+ *
+ * @example
+ * ```ts
+ * normalizeLegacyOutputFormat("table") // "pretty"
+ * normalizeLegacyOutputFormat("compress") // "compress"
+ * normalizeLegacyOutputFormat(123) // undefined
+ * ```
+ */
+export function normalizeLegacyOutputFormat(v) {
+    if (v === "table")
+        return "pretty";
+    if (isValidFormat(v))
+        return v;
+    return undefined;
+}

package/lib/index.d.ts

@@ -0,0 +1,209 @@
+/**
+ * @fileoverview Public API surface of the `@yuntoo/cli-framework` package.
+ *
+ * Re-exports all public types and values from the framework sub-modules.
+ * Import from this file rather than deep-importing internal modules to
+ * ensure compatibility across minor version bumps.
+ *
+ * @example
+ * ```ts
+ * import { runCommandWithAdapter, createCliErrors, type CommandDefinition } from "@yuntoo/cli-framework";
+ * ```
+ */
+export type { 
+/** @see ./framework/types.ts */
+ArgDef, FlagDef, CommandDefinition, CommandResult, DryRunResult, RuntimeContextBase, RuntimeContext, OutputFormat, OutputEnvelope, Risk, } from "./framework/types.js";
+export { 
+/** @see ./framework/types.ts */
+riskLevelOrder, normalizeLegacyOutputFormat, isValidFormat, } from "./framework/types.js";
+export { CliError, createCliErrors } from "./errors.js";
+export type { 
+/**
+ * @see ./errors.ts
+ * @description Shape of the factory returned by `createCliErrors`.
+ */
+CliErrorsShape, 
+/**
+ * @see ./errors.ts
+ * @description Configuration for `createCliErrors`.
+ */
+CliErrorFactoryOptions, } from "./errors.js";
+export { buildAllFlags } from "./framework/build-all-flags.js";
+export type { 
+/**
+ * @see ./framework/build-all-flags.ts
+ * @description Options for `buildAllFlags`.
+ */
+BuildAllFlagsOptions, } from "./framework/build-all-flags.js";
+export { createFlagHelpers } from "./framework/flags.js";
+export type { 
+/**
+ * @see ./framework/flags.ts
+ * @description Parsed flag map returned by `parseFlags`.
+ */
+ParsedFlags, } from "./framework/flags.js";
+export { createHelpGenerators } from "./framework/help.js";
+export type { 
+/**
+ * @see ./framework/help.ts
+ * @description A global flag shown in the top-level help.
+ */
+GlobalHelpFlag, 
+/**
+ * @see ./framework/help.ts
+ * @description A command entry in a service's help listing.
+ */
+HelpCommandListing, 
+/**
+ * @see ./framework/help.ts
+ * @description A service entry in the help registry.
+ */
+HelpServiceEntry, 
+/**
+ * @see ./framework/help.ts
+ * @description Options for `createHelpGenerators`.
+ */
+HelpGeneratorOptions, } from "./framework/help.js";
+export { buildSchemaPayload } from "./framework/schema-export.js";
+export type { 
+/**
+ * @see ./framework/schema-export.ts
+ * @description A serialized regex pattern (RegExp replaced with plain fields).
+ */
+SerializedFlagPattern, 
+/**
+ * @see ./framework/schema-export.ts
+ * @description A serialized flag definition for JSON export.
+ */
+SerializedFlag, 
+/**
+ * @see ./framework/schema-export.ts
+ * @description A serialized command entry for the schema payload.
+ */
+SchemaCommandEntry, 
+/**
+ * @see ./framework/schema-export.ts
+ * @description A serialized service entry for the schema payload.
+ */
+SchemaServiceEntry, 
+/**
+ * @see ./framework/schema-export.ts
+ * @description The root schema payload object.
+ */
+SchemaPayload, 
+/**
+ * @see ./framework/schema-export.ts
+ * @description A stripped-down command listing used during schema build.
+ */
+SchemaCommandListing, 
+/**
+ * @see ./framework/schema-export.ts
+ * @description A stripped-down service listing used during schema build.
+ */
+SchemaServiceListing, 
+/**
+ * @see ./framework/schema-export.ts
+ * @description Options for `buildSchemaPayload`.
+ */
+BuildSchemaOptions, } from "./framework/schema-export.js";
+export { runCommandWithAdapter } from "./framework/runner.js";
+export type { 
+/**
+ * @see ./framework/runner.ts
+ * @description Raw environment values from the CLI entry point.
+ */
+RunnerEnvBase, 
+/**
+ * @see ./framework/runner.ts
+ * @description Values produced by the adapter's `prepare` hook.
+ */
+PreparedRuntimeValues, 
+/**
+ * @see ./framework/runner.ts
+ * @description Risk policy governing risk ceiling enforcement.
+ */
+RiskPolicy, 
+/**
+ * @see ./framework/runner.ts
+ * @description Options passed to `adapter.confirmHighRisk`.
+ */
+ConfirmHighRiskOptions, 
+/**
+ * @see ./framework/runner.ts
+ * @description Context object passed to adapter hooks before execution.
+ */
+ExecuteHookOptions, 
+/**
+ * @see ./framework/runner.ts
+ * @description Context object passed to the `finalize` hook.
+ */
+FinalizeHookOptions, 
+/**
+ * @see ./framework/runner.ts
+ * @description Adapter interface bridging the framework runner to a concrete CLI.
+ */
+RunnerAdapter, } from "./framework/runner.js";
+export { 
+/** @see ./framework/runner-shared.ts */
+resolveJqFilter, 
+/** @see ./framework/runner-shared.ts */
+resolveFormat, 
+/** @see ./framework/runner-shared.ts */
+buildRuntimeContext, 
+/** @see ./framework/runner-shared.ts */
+resolveOutputConfig, 
+/** @see ./framework/runner-shared.ts */
+assertRiskWithinLevel, 
+/** @see ./framework/runner-shared.ts */
+runDryRunIfNeeded, 
+/** @see ./framework/runner-shared.ts */
+requireConfirmationPrompt, } from "./framework/runner-shared.js";
+export type { 
+/**
+ * @see ./framework/runner-shared.ts
+ * @description Options for `resolveOutputConfig`.
+ */
+ResolveOutputOptions, 
+/**
+ * @see ./framework/runner-shared.ts
+ * @description Output configuration resolved by `resolveOutputConfig`.
+ */
+ResolvedOutputConfig, 
+/**
+ * @see ./framework/runner-shared.ts
+ * @description Options for `buildRuntimeContext`.
+ */
+BuildRuntimeContextOptions, 
+/**
+ * @see ./framework/runner-shared.ts
+ * @description Options for `assertRiskWithinLevel`.
+ */
+AssertRiskWithinLevelOptions, 
+/**
+ * @see ./framework/runner-shared.ts
+ * @description Options for `runDryRunIfNeeded`.
+ */
+RunDryRunOptions, 
+/**
+ * @see ./framework/runner-shared.ts
+ * @description Options for `requireConfirmationPrompt`.
+ */
+ConfirmationPromptOptions, } from "./framework/runner-shared.js";
+export { 
+/** @see ./framework/response.ts */
+extractList, 
+/** @see ./framework/response.ts */
+extractPaging, } from "./framework/response.js";
+export type { 
+/**
+ * @see ./framework/response.ts
+ * @description Pagination metadata in list responses.
+ */
+Paging, 
+/**
+ * @see ./framework/response.ts
+ * @description List response wrapper with records and optional paging.
+ */
+ListResponse, } from "./framework/response.js";
+export { formatOutput } from "./framework/output.js";
+export { createJqFilter } from "./utils/apply-jq-filter.js";

package/lib/index.js

@@ -0,0 +1,52 @@
+/**
+ * @fileoverview Public API surface of the `@yuntoo/cli-framework` package.
+ *
+ * Re-exports all public types and values from the framework sub-modules.
+ * Import from this file rather than deep-importing internal modules to
+ * ensure compatibility across minor version bumps.
+ *
+ * @example
+ * ```ts
+ * import { runCommandWithAdapter, createCliErrors, type CommandDefinition } from "@yuntoo/cli-framework";
+ * ```
+ */
+export { 
+/** @see ./framework/types.ts */
+riskLevelOrder, normalizeLegacyOutputFormat, isValidFormat, } from "./framework/types.js";
+// ─── Errors ───────────────────────────────────────────────────────────────────
+export { CliError, createCliErrors } from "./errors.js";
+// ─── Flag Pipeline ─────────────────────────────────────────────────────────────
+export { buildAllFlags } from "./framework/build-all-flags.js";
+export { createFlagHelpers } from "./framework/flags.js";
+// ─── Help Generation ───────────────────────────────────────────────────────────
+export { createHelpGenerators } from "./framework/help.js";
+// ─── Schema Export ─────────────────────────────────────────────────────────────
+export { buildSchemaPayload } from "./framework/schema-export.js";
+// ─── Runner ────────────────────────────────────────────────────────────────────
+export { runCommandWithAdapter } from "./framework/runner.js";
+// ─── Runner Shared Utilities ────────────────────────────────────────────────────
+export { 
+/** @see ./framework/runner-shared.ts */
+resolveJqFilter, 
+/** @see ./framework/runner-shared.ts */
+resolveFormat, 
+/** @see ./framework/runner-shared.ts */
+buildRuntimeContext, 
+/** @see ./framework/runner-shared.ts */
+resolveOutputConfig, 
+/** @see ./framework/runner-shared.ts */
+assertRiskWithinLevel, 
+/** @see ./framework/runner-shared.ts */
+runDryRunIfNeeded, 
+/** @see ./framework/runner-shared.ts */
+requireConfirmationPrompt, } from "./framework/runner-shared.js";
+// ─── Response Utilities ────────────────────────────────────────────────────────
+export { 
+/** @see ./framework/response.ts */
+extractList, 
+/** @see ./framework/response.ts */
+extractPaging, } from "./framework/response.js";
+// ─── Output Formatting ─────────────────────────────────────────────────────────
+export { formatOutput } from "./framework/output.js";
+// ─── JQ Filter ────────────────────────────────────────────────────────────────
+export { createJqFilter } from "./utils/apply-jq-filter.js";

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

@@ -0,0 +1,33 @@
+/**
+ * @fileoverview jq post-filter integration for JSON output.
+ *
+ * Wraps the `jq` command-line tool (https://jqlang.org) to apply an
+ * expression filter to a JSON stream. Used by the output formatter when
+ * the user supplies `--jq <expression>` together with `--format json`
+ * 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`.
+ *
+ * @module apply-jq-filter
+ */
+import type { CliErrorsShape } from "../errors.js";
+/**
+ * Creates a jq filter function bound to a specific error factory.
+ *
+ * The returned function accepts a JSON string and a jq expression, spawns
+ * the jq binary, and returns the filtered output string. On failure it
+ * throws a typed {@link CliError} with code `"validation_error"`.
+ *
+ * @param cliErrors - Error factory providing `validation` for error reporting.
+ * @returns An `applyJqFilter(jsonInput, expr)` function.
+ *
+ * @example
+ * ```ts
+ * const applyJqFilter = createJqFilter(cliErrors);
+ * const filtered = applyJqFilter('{"items":[{"id":1}]}\n', ".[].id");
+ * // filtered === "1\n"
+ * ```
+ */
+export declare function createJqFilter(cliErrors: Pick<CliErrorsShape, "validation">): (jsonInput: string, expr: string) => string;

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

@@ -0,0 +1,99 @@
+/**
+ * @fileoverview jq post-filter integration for JSON output.
+ *
+ * Wraps the `jq` command-line tool (https://jqlang.org) to apply an
+ * expression filter to a JSON stream. Used by the output formatter when
+ * the user supplies `--jq <expression>` together with `--format json`
+ * 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`.
+ *
+ * @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;
+/**
+ * Creates a jq filter function bound to a specific error factory.
+ *
+ * The returned function accepts a JSON string and a jq expression, spawns
+ * the jq binary, and returns the filtered output string. On failure it
+ * throws a typed {@link CliError} with code `"validation_error"`.
+ *
+ * @param cliErrors - Error factory providing `validation` for error reporting.
+ * @returns An `applyJqFilter(jsonInput, expr)` function.
+ *
+ * @example
+ * ```ts
+ * const applyJqFilter = createJqFilter(cliErrors);
+ * const filtered = applyJqFilter('{"items":[{"id":1}]}\n', ".[].id");
+ * // filtered === "1\n"
+ * ```
+ */
+export function createJqFilter(cliErrors) {
+    /**
+     * Applies a jq expression filter to a JSON input string.
+     *
+     * @param jsonInput - Complete JSON line(s) to filter.
+     * @param expr      - jq expression (e.g. `.[].name`).
+     * @returns The jq-filtered output string.
+     * @throws {@link CliError} with code `"validation_error"` when:
+     *          - The jq binary cannot be found.
+     *          - The expression is invalid.
+     *          - The input is not valid JSON.
+     */
+    return function applyJqFilter(jsonInput, expr) {
+        const jqCmd = resolveJqBinary();
+        try {
+            return execFileSync(jqCmd, [expr], {
+                input: jsonInput,
+                encoding: "utf8",
+                maxBuffer: MAX_BUFFER,
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+        }
+        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");
+            }
+            const stderr = e.stderr?.toString?.().trim() ?? "";
+            const fallback = (e.message ?? String(err)).trim();
+            const body = stderr || fallback;
+            const msg = /^\s*jq:/i.test(body) ? body : `jq: ${body}`;
+            throw cliErrors.validation(msg);
+        }
+    };
+}
+/**
+ * Resolves the path to the jq executable.
+ *
+ * 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.
+ *
+ * @returns Absolute path to the jq executable.
+ */
+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;
+    }
+    catch {
+        // node-jq not installed or resolution failed — fall through to PATH
+    }
+    return "jq";
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@lovrabet/cli-framework",
+  "version": "0.1.1-beta.0",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    }
+  },
+  "files": [
+    "lib"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf lib && tsc && echo 'cli-framework build done'",
+    "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"
+  },
+  "devDependencies": {
+    "@types/node": "^24.5.2",
+    "typescript": "latest",
+    "vitest": "^4.1.2"
+  }
+}