@lovrabet/cli-framework 1.0.2 → 1.0.4-beta.2

package/lib/framework/output.d.ts

@@ -10,6 +10,8 @@
  * 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

@@ -12,12 +12,12 @@
 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,13 @@ Paging,
  * @description List response wrapper with records and optional paging.
  */
 ListResponse, } from "./framework/response.js";
-export { formatOutput } from "./framework/output.js";
+export * from "./service-tree/index.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

@@ -46,7 +46,11 @@ export {
 extractList, 
 /** @see ./framework/response.ts */
 extractPaging, } from "./framework/response.js";
+// ─── Service Tree Manifest Utilities ─────────────────────────────────────────
+export * from "./service-tree/index.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/service-tree/compile.d.ts

@@ -0,0 +1,2 @@
+import type { NormalizedServiceTreeCommand, ServiceTreeCompileInput, ServiceTreeExecutionPlan } from "./types.js";
+export declare function compileServiceTreeCommand(command: NormalizedServiceTreeCommand, input?: ServiceTreeCompileInput): ServiceTreeExecutionPlan;

package/lib/service-tree/compile.js

@@ -0,0 +1,128 @@
+import { stripParamsPrefix } from "./path.js";
+export function compileServiceTreeCommand(command, input = {}) {
+    const params = cloneRecord(command.baseParams);
+    for (const rule of command.mapTo) {
+        const value = resolveRuleValue(rule, command, input);
+        if (value === undefined)
+            continue;
+        if (rule.omitEmpty !== false && value === "")
+            continue;
+        const transformed = transformValue(value, rule.transform);
+        const targetPath = rule.operator
+            ? `${stripParamsPrefix(rule.target)}.${rule.operator}`
+            : stripParamsPrefix(rule.target);
+        setDeep(params, targetPath, transformed);
+    }
+    return {
+        kind: command.target.kind,
+        command: command.target.command,
+        appRef: command.target.appRef,
+        datasetCode: command.target.datasetCode,
+        datatable: command.target.datatable,
+        sqlCode: command.target.sqlCode,
+        bffCode: command.target.bffCode,
+        bffId: command.target.bffId,
+        scriptName: command.target.scriptName,
+        params,
+    };
+}
+function resolveRuleValue(rule, command, input) {
+    if (rule.source === undefined || rule.source === "const" || rule.source.startsWith("const.")) {
+        return rule.value;
+    }
+    if (rule.source.startsWith("flags.")) {
+        const name = rule.source.slice("flags.".length);
+        return readFlagValue(name, command, input.flags || {});
+    }
+    if (rule.source.startsWith("args.")) {
+        const name = rule.source.slice("args.".length);
+        return readArgValue(name, command, input.args || {});
+    }
+    if (rule.source.startsWith("context.")) {
+        const name = rule.source.slice("context.".length);
+        return readPath(input.context || {}, name);
+    }
+    if (rule.source.startsWith("ctx.")) {
+        const name = rule.source.slice("ctx.".length);
+        return readPath(input.context || {}, name);
+    }
+    return undefined;
+}
+function readFlagValue(name, command, flags) {
+    if (Object.prototype.hasOwnProperty.call(flags, name))
+        return flags[name];
+    const flag = command.flags.find((item) => item.name === name || item.cliName === name);
+    if (flag) {
+        if (Object.prototype.hasOwnProperty.call(flags, flag.cliName))
+            return flags[flag.cliName];
+        if (Object.prototype.hasOwnProperty.call(flags, flag.name))
+            return flags[flag.name];
+        if (flag.default !== undefined)
+            return flag.default;
+    }
+    return undefined;
+}
+function readArgValue(name, command, args) {
+    if (Array.isArray(args)) {
+        const index = /^\d+$/.test(name)
+            ? Number(name)
+            : command.args.findIndex((arg) => arg.name === name);
+        return index >= 0 ? args[index] : undefined;
+    }
+    return args[name];
+}
+function readPath(value, path) {
+    if (!path)
+        return value;
+    const parts = path.split(".").filter(Boolean);
+    let cursor = value;
+    for (const part of parts) {
+        if (!isRecord(cursor) || !Object.prototype.hasOwnProperty.call(cursor, part)) {
+            return undefined;
+        }
+        cursor = cursor[part];
+    }
+    return cursor;
+}
+function transformValue(value, transform) {
+    if (!transform)
+        return value;
+    if (transform === "string")
+        return String(value);
+    if (transform === "number")
+        return typeof value === "number" ? value : Number(value);
+    if (transform === "boolean") {
+        if (typeof value === "boolean")
+            return value;
+        if (typeof value === "string")
+            return value === "true" || value === "1";
+        return Boolean(value);
+    }
+    if (transform === "json") {
+        if (typeof value !== "string")
+            return value;
+        return JSON.parse(value);
+    }
+    return value;
+}
+function setDeep(target, path, value) {
+    const parts = path.split(".").filter(Boolean);
+    let cursor = target;
+    parts.forEach((part, index) => {
+        if (index === parts.length - 1) {
+            cursor[part] = value;
+            return;
+        }
+        const existing = cursor[part];
+        if (!isRecord(existing)) {
+            cursor[part] = {};
+        }
+        cursor = cursor[part];
+    });
+}
+function cloneRecord(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/lib/service-tree/index.d.ts

@@ -0,0 +1,6 @@
+export type { NormalizedServiceTree, NormalizedServiceTreeCommand, NormalizedServiceTreeFlag, NormalizedServiceTreeTarget, ServiceTreeAppBinding, ServiceTreeArg, ServiceTreeCommand, ServiceTreeCompileInput, ServiceTreeDatasetResolver, ServiceTreeDatasetResolverInput, ServiceTreeExecutionPlan, ServiceTreeFlag, ServiceTreeManifest, ServiceTreeMapTo, ServiceTreeMapToObject, ServiceTreeMapToRule, ServiceTreeMapTransform, ServiceTreeMatch, ServiceTreeServiceInfo, ServiceTreeTarget, ServiceTreeTargetCommand, ServiceTreeTargetKind, ServiceTreeValidationIssue, ServiceTreeValidationReport, ServiceTreeValueType, } from "./types.js";
+export { compileServiceTreeCommand } from "./compile.js";
+export { matchServiceTreeCommand } from "./match.js";
+export { normalizeServiceTreeManifest } from "./normalize.js";
+export { isCommandSegment, isDatatableName, isDatasetCode, isServiceCode, pathToString, splitServiceTreePath, stripParamsPrefix, toKebabCase, } from "./path.js";
+export { validateServiceTreeManifest } from "./validate.js";

package/lib/service-tree/index.js

@@ -0,0 +1,5 @@
+export { compileServiceTreeCommand } from "./compile.js";
+export { matchServiceTreeCommand } from "./match.js";
+export { normalizeServiceTreeManifest } from "./normalize.js";
+export { isCommandSegment, isDatatableName, isDatasetCode, isServiceCode, pathToString, splitServiceTreePath, stripParamsPrefix, toKebabCase, } from "./path.js";
+export { validateServiceTreeManifest } from "./validate.js";

package/lib/service-tree/map-to.d.ts

@@ -0,0 +1,2 @@
+import type { ServiceTreeFlag, ServiceTreeMapTo, ServiceTreeMapToRule } from "./types.js";
+export declare function normalizeMapTo(mapTo: ServiceTreeMapTo | undefined, flags?: ServiceTreeFlag[]): ServiceTreeMapToRule[];

package/lib/service-tree/map-to.js

@@ -0,0 +1,27 @@
+export function normalizeMapTo(mapTo, flags = []) {
+    const rules = [];
+    if (Array.isArray(mapTo)) {
+        rules.push(...mapTo.map((rule) => ({ ...rule })));
+    }
+    else if (mapTo && typeof mapTo === "object") {
+        for (const [source, target] of Object.entries(mapTo)) {
+            if (typeof target === "string") {
+                rules.push({ source, target });
+            }
+            else {
+                rules.push({ source, ...target });
+            }
+        }
+    }
+    for (const flag of flags) {
+        if (!flag.mapTo)
+            continue;
+        if (typeof flag.mapTo === "string") {
+            rules.push({ source: `flags.${flag.name}`, target: flag.mapTo });
+        }
+        else {
+            rules.push({ source: `flags.${flag.name}`, ...flag.mapTo });
+        }
+    }
+    return rules;
+}

package/lib/service-tree/match.d.ts

@@ -0,0 +1,2 @@
+import type { NormalizedServiceTree, ServiceTreeMatch } from "./types.js";
+export declare function matchServiceTreeCommand(tree: NormalizedServiceTree, input: string | string[]): ServiceTreeMatch | undefined;

package/lib/service-tree/match.js

@@ -0,0 +1,19 @@
+import { splitServiceTreePath } from "./path.js";
+export function matchServiceTreeCommand(tree, input) {
+    const path = splitServiceTreePath(input);
+    let best;
+    for (const command of tree.commands) {
+        if (!startsWith(path, command.fullPath))
+            continue;
+        const remainingArgs = path.slice(command.fullPath.length);
+        if (!best || command.fullPath.length > best.command.fullPath.length) {
+            best = { command, remainingArgs };
+        }
+    }
+    return best;
+}
+function startsWith(path, prefix) {
+    if (prefix.length > path.length)
+        return false;
+    return prefix.every((segment, index) => path[index] === segment);
+}

package/lib/service-tree/normalize.d.ts

@@ -0,0 +1,2 @@
+import type { NormalizedServiceTree, ServiceTreeManifest } from "./types.js";
+export declare function normalizeServiceTreeManifest(manifest: ServiceTreeManifest): NormalizedServiceTree;

package/lib/service-tree/normalize.js

@@ -0,0 +1,35 @@
+import { normalizeMapTo } from "./map-to.js";
+import { splitServiceTreePath, toKebabCase } from "./path.js";
+const DEFAULT_PROTOCOL = "lovrabet.service-tree/v1";
+export function normalizeServiceTreeManifest(manifest) {
+    const serviceCode = manifest.service.code;
+    return {
+        protocol: manifest.protocol || DEFAULT_PROTOCOL,
+        version: manifest.version,
+        service: { ...manifest.service },
+        appBindings: { ...(manifest.appBindings || {}) },
+        commands: manifest.commands.map((command) => {
+            const path = splitServiceTreePath(command.path);
+            const fullPath = path[0] === serviceCode ? path : [serviceCode, ...path];
+            const flags = (command.flags || []).map((flag) => ({
+                ...flag,
+                cliName: flag.cliName ? toKebabCase(flag.cliName) : toKebabCase(flag.name),
+            }));
+            return {
+                path,
+                fullPath,
+                cliPath: fullPath.join(" "),
+                description: command.description,
+                risk: command.risk || "read",
+                args: command.args || [],
+                flags,
+                target: { ...command.target },
+                baseParams: {
+                    ...(command.target.params || {}),
+                    ...(command.params || {}),
+                },
+                mapTo: normalizeMapTo(command.mapTo, flags),
+            };
+        }),
+    };
+}

package/lib/service-tree/path.d.ts

@@ -0,0 +1,8 @@
+export declare function splitServiceTreePath(path: string | string[]): string[];
+export declare function toKebabCase(value: string): string;
+export declare function isCommandSegment(value: string): boolean;
+export declare function isServiceCode(value: string): boolean;
+export declare function isDatatableName(value: string): boolean;
+export declare function isDatasetCode(value: string): boolean;
+export declare function stripParamsPrefix(path: string): string;
+export declare function pathToString(path: string[]): string;

package/lib/service-tree/path.js

@@ -0,0 +1,30 @@
+export function splitServiceTreePath(path) {
+    const parts = Array.isArray(path) ? path : path.trim().split(/\s+/);
+    return parts.map((part) => part.trim()).filter(Boolean);
+}
+export function toKebabCase(value) {
+    return value
+        .trim()
+        .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+        .replace(/[_\s]+/g, "-")
+        .replace(/-+/g, "-")
+        .toLowerCase();
+}
+export function isCommandSegment(value) {
+    return /^[a-z][a-z0-9-]*$/.test(value);
+}
+export function isServiceCode(value) {
+    return /^[a-z][a-z0-9-]*$/.test(value);
+}
+export function isDatatableName(value) {
+    return /^[A-Za-z][A-Za-z0-9_]*$/.test(value);
+}
+export function isDatasetCode(value) {
+    return /^[a-f0-9]{32}$/i.test(value);
+}
+export function stripParamsPrefix(path) {
+    return path.startsWith("params.") ? path.slice("params.".length) : path;
+}
+export function pathToString(path) {
+    return path.join(" ");
+}

package/lib/service-tree/types.d.ts

@@ -0,0 +1,132 @@
+import type { Risk } from "../framework/types.js";
+export type ServiceTreeTargetKind = "data" | "sql" | "bff";
+export type ServiceTreeTargetCommand = "filter" | "getOne" | "aggregate" | "create" | "batchCreate" | "update" | "delete" | "exec";
+export type ServiceTreeValueType = "string" | "number" | "boolean" | "json";
+export type ServiceTreeMapTransform = ServiceTreeValueType;
+export interface ServiceTreeServiceInfo {
+    code: string;
+    name?: string;
+    description?: string;
+}
+export interface ServiceTreeAppBinding {
+    app?: string;
+    appcode?: string;
+    appCode?: string;
+    env?: string;
+}
+export interface ServiceTreeArg {
+    name: string;
+    description?: string;
+    required?: boolean;
+}
+export interface ServiceTreeMapToRule {
+    source?: string;
+    target: string;
+    value?: unknown;
+    transform?: ServiceTreeMapTransform;
+    operator?: string;
+    omitEmpty?: boolean;
+}
+export type ServiceTreeMapToObject = Record<string, string | Omit<ServiceTreeMapToRule, "source">>;
+export type ServiceTreeMapTo = ServiceTreeMapToRule[] | ServiceTreeMapToObject;
+export interface ServiceTreeFlag {
+    name: string;
+    cliName?: string;
+    type: ServiceTreeValueType;
+    description?: string;
+    required?: boolean;
+    default?: unknown;
+    enum?: string[];
+    mapTo?: string | Omit<ServiceTreeMapToRule, "source">;
+}
+export interface ServiceTreeTarget {
+    kind: ServiceTreeTargetKind;
+    command: ServiceTreeTargetCommand;
+    appRef?: string;
+    datasetCode?: string;
+    datatable?: string;
+    sqlCode?: string;
+    bffCode?: string;
+    bffId?: string | number;
+    scriptName?: string;
+    params?: Record<string, unknown>;
+}
+export interface ServiceTreeCommand {
+    path: string | string[];
+    description?: string;
+    risk?: Risk;
+    args?: ServiceTreeArg[];
+    flags?: ServiceTreeFlag[];
+    target: ServiceTreeTarget;
+    params?: Record<string, unknown>;
+    mapTo?: ServiceTreeMapTo;
+}
+export interface ServiceTreeManifest {
+    protocol?: string;
+    version: string;
+    service: ServiceTreeServiceInfo;
+    appBindings?: Record<string, ServiceTreeAppBinding>;
+    commands: ServiceTreeCommand[];
+}
+export interface NormalizedServiceTreeFlag extends ServiceTreeFlag {
+    cliName: string;
+}
+export interface NormalizedServiceTreeTarget extends ServiceTreeTarget {
+    command: ServiceTreeTargetCommand;
+}
+export interface NormalizedServiceTreeCommand {
+    path: string[];
+    fullPath: string[];
+    cliPath: string;
+    description?: string;
+    risk: Risk;
+    args: ServiceTreeArg[];
+    flags: NormalizedServiceTreeFlag[];
+    target: NormalizedServiceTreeTarget;
+    baseParams: Record<string, unknown>;
+    mapTo: ServiceTreeMapToRule[];
+}
+export interface NormalizedServiceTree {
+    protocol: string;
+    version: string;
+    service: ServiceTreeServiceInfo;
+    appBindings: Record<string, ServiceTreeAppBinding>;
+    commands: NormalizedServiceTreeCommand[];
+}
+export interface ServiceTreeValidationIssue {
+    level: "error" | "warning";
+    path: string;
+    message: string;
+}
+export interface ServiceTreeValidationReport {
+    ok: boolean;
+    errors: ServiceTreeValidationIssue[];
+    warnings: ServiceTreeValidationIssue[];
+}
+export interface ServiceTreeMatch {
+    command: NormalizedServiceTreeCommand;
+    remainingArgs: string[];
+}
+export interface ServiceTreeCompileInput {
+    flags?: Record<string, unknown>;
+    args?: Record<string, unknown> | string[];
+    context?: Record<string, unknown>;
+}
+export interface ServiceTreeExecutionPlan {
+    kind: ServiceTreeTargetKind;
+    command: ServiceTreeTargetCommand;
+    appRef?: string;
+    datasetCode?: string;
+    datatable?: string;
+    sqlCode?: string;
+    bffCode?: string;
+    bffId?: string | number;
+    scriptName?: string;
+    params: Record<string, unknown>;
+}
+export interface ServiceTreeDatasetResolverInput {
+    appRef?: string;
+    datatable: string;
+    commandPath: string[];
+}
+export type ServiceTreeDatasetResolver = (input: ServiceTreeDatasetResolverInput) => string | undefined | Promise<string | undefined>;

package/lib/service-tree/types.js

@@ -0,0 +1 @@
+export {};

package/lib/service-tree/validate.d.ts

@@ -0,0 +1,2 @@
+import type { ServiceTreeValidationReport } from "./types.js";
+export declare function validateServiceTreeManifest(manifest: unknown): ServiceTreeValidationReport;

package/lib/service-tree/validate.js

@@ -0,0 +1,188 @@
+import { isCommandSegment, isDatatableName, isDatasetCode, isServiceCode, splitServiceTreePath, toKebabCase, } from "./path.js";
+const DATA_COMMANDS = new Set(["filter", "getOne", "aggregate", "create", "batchCreate", "update", "delete"]);
+const SQL_COMMANDS = new Set(["exec"]);
+const BFF_COMMANDS = new Set(["exec"]);
+const VALUE_TYPES = new Set(["string", "number", "boolean", "json"]);
+export function validateServiceTreeManifest(manifest) {
+    const issues = [];
+    if (!isRecord(manifest)) {
+        push(issues, "error", "$", "Manifest must be a JSON object.");
+        return buildReport(issues);
+    }
+    if (typeof manifest.version !== "string" || !manifest.version.trim()) {
+        push(issues, "error", "$.version", "version is required.");
+    }
+    if (!isRecord(manifest.service)) {
+        push(issues, "error", "$.service", "service is required.");
+    }
+    else if (typeof manifest.service.code !== "string" || !isServiceCode(manifest.service.code)) {
+        push(issues, "error", "$.service.code", "service.code must be lower kebab-case.");
+    }
+    if (!Array.isArray(manifest.commands) || manifest.commands.length === 0) {
+        push(issues, "error", "$.commands", "commands must be a non-empty array.");
+        return buildReport(issues);
+    }
+    const serviceCode = isRecord(manifest.service) && typeof manifest.service.code === "string"
+        ? manifest.service.code
+        : "";
+    const seenPaths = new Set();
+    manifest.commands.forEach((command, index) => {
+        validateCommand(command, index, serviceCode, seenPaths, issues);
+    });
+    return buildReport(issues);
+}
+function validateCommand(command, index, serviceCode, seenPaths, issues) {
+    const base = `$.commands[${index}]`;
+    if (!isRecord(command)) {
+        push(issues, "error", base, "Command must be an object.");
+        return;
+    }
+    const path = splitServiceTreePath(command.path || []);
+    if (path.length === 0) {
+        push(issues, "error", `${base}.path`, "path is required.");
+    }
+    for (const [partIndex, segment] of path.entries()) {
+        if (!isCommandSegment(segment)) {
+            push(issues, "error", `${base}.path[${partIndex}]`, "Command path segments must be lower kebab-case.");
+        }
+    }
+    const fullPath = path[0] === serviceCode ? path : [serviceCode, ...path];
+    const fullKey = fullPath.join(" ");
+    if (seenPaths.has(fullKey)) {
+        push(issues, "error", `${base}.path`, `Duplicate command path: ${fullKey}.`);
+    }
+    seenPaths.add(fullKey);
+    validateTarget(command.target, `${base}.target`, issues);
+    validateFlags(command.flags, `${base}.flags`, issues);
+    validateMapTo(command.mapTo, `${base}.mapTo`, issues);
+}
+function validateTarget(target, path, issues) {
+    if (!isRecord(target)) {
+        push(issues, "error", path, "target is required.");
+        return;
+    }
+    const typed = target;
+    if (typed.kind === "data") {
+        if (!DATA_COMMANDS.has(typed.command)) {
+            push(issues, "error", `${path}.command`, "data target command is not supported.");
+        }
+        if (!typed.datasetCode && !typed.datatable) {
+            push(issues, "error", path, "data target requires datasetCode or datatable.");
+        }
+        if (typed.datasetCode && !isDatasetCode(typed.datasetCode)) {
+            push(issues, "error", `${path}.datasetCode`, "datasetCode must be a 32-character code.");
+        }
+        if (typed.datatable && !isDatatableName(typed.datatable)) {
+            push(issues, "error", `${path}.datatable`, "datatable must be a valid physical table name.");
+        }
+        return;
+    }
+    if (typed.kind === "sql") {
+        if (!SQL_COMMANDS.has(typed.command)) {
+            push(issues, "error", `${path}.command`, "sql target command is not supported.");
+        }
+        if (!typed.sqlCode) {
+            push(issues, "error", `${path}.sqlCode`, "sql target requires sqlCode.");
+        }
+        return;
+    }
+    if (typed.kind === "bff") {
+        if (!BFF_COMMANDS.has(typed.command)) {
+            push(issues, "error", `${path}.command`, "bff target command is not supported.");
+        }
+        if (!typed.bffCode && !typed.bffId && !typed.scriptName) {
+            push(issues, "error", path, "bff target requires bffCode, bffId, or scriptName.");
+        }
+        return;
+    }
+    push(issues, "error", `${path}.kind`, "target.kind must be data, sql, or bff.");
+}
+function validateFlags(flags, path, issues) {
+    if (flags === undefined)
+        return;
+    if (!Array.isArray(flags)) {
+        push(issues, "error", path, "flags must be an array.");
+        return;
+    }
+    const seen = new Set();
+    flags.forEach((flag, index) => {
+        const flagPath = `${path}[${index}]`;
+        if (!isRecord(flag)) {
+            push(issues, "error", flagPath, "flag must be an object.");
+            return;
+        }
+        if (typeof flag.name !== "string" || !flag.name.trim()) {
+            push(issues, "error", `${flagPath}.name`, "flag.name is required.");
+            return;
+        }
+        if (seen.has(flag.name)) {
+            push(issues, "error", `${flagPath}.name`, `Duplicate flag name: ${flag.name}.`);
+        }
+        seen.add(flag.name);
+        const cliName = typeof flag.cliName === "string" ? flag.cliName : toKebabCase(flag.name);
+        if (cliName !== toKebabCase(cliName)) {
+            push(issues, "error", `${flagPath}.cliName`, "flag.cliName must be kebab-case.");
+        }
+        if (typeof flag.type !== "string" || !VALUE_TYPES.has(flag.type)) {
+            push(issues, "error", `${flagPath}.type`, "flag.type must be string, number, boolean, or json.");
+        }
+    });
+}
+function validateMapTo(mapTo, path, issues) {
+    if (mapTo === undefined)
+        return;
+    if (Array.isArray(mapTo)) {
+        mapTo.forEach((rule, index) => validateMapRule(rule, `${path}[${index}]`, issues));
+        return;
+    }
+    if (isRecord(mapTo)) {
+        for (const [source, target] of Object.entries(mapTo)) {
+            if (!isValidSource(source)) {
+                push(issues, "error", `${path}.${source}`, "mapTo source must start with flags., args., const., context., or ctx.");
+            }
+            if (typeof target === "string") {
+                if (!target.trim())
+                    push(issues, "error", `${path}.${source}`, "mapTo target is required.");
+            }
+            else {
+                validateMapRule({ source, ...target }, `${path}.${source}`, issues);
+            }
+        }
+        return;
+    }
+    push(issues, "error", path, "mapTo must be an object or an array.");
+}
+function validateMapRule(rule, path, issues) {
+    if (!isRecord(rule)) {
+        push(issues, "error", path, "mapTo rule must be an object.");
+        return;
+    }
+    if (rule.source !== undefined && (typeof rule.source !== "string" || !isValidSource(rule.source))) {
+        push(issues, "error", `${path}.source`, "mapTo source must start with flags., args., const., context., or ctx.");
+    }
+    if (typeof rule.target !== "string" || !rule.target.trim()) {
+        push(issues, "error", `${path}.target`, "mapTo target is required.");
+    }
+    if (rule.transform !== undefined && (typeof rule.transform !== "string" || !VALUE_TYPES.has(rule.transform))) {
+        push(issues, "error", `${path}.transform`, "mapTo transform must be string, number, boolean, or json.");
+    }
+}
+function isValidSource(source) {
+    return source === "const"
+        || source.startsWith("flags.")
+        || source.startsWith("args.")
+        || source.startsWith("const.")
+        || source.startsWith("context.")
+        || source.startsWith("ctx.");
+}
+function buildReport(issues) {
+    const errors = issues.filter((issue) => issue.level === "error");
+    const warnings = issues.filter((issue) => issue.level === "warning");
+    return { ok: errors.length === 0, errors, warnings };
+}
+function push(issues, level, path, message) {
+    issues.push({ level, path, message });
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

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.2",
+  "version": "1.0.4-beta.2",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -11,13 +11,15 @@
     }
   },
   "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",
@@ -28,7 +30,7 @@
   },
   "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.