@lovrabet/cli-framework 0.1.1-beta.0

package/lib/framework/runner-shared.js

@@ -0,0 +1,240 @@
+/**
+ * @fileoverview Shared utilities used by the framework runner.
+ *
+ * Provides pure functions for:
+ * - Resolving the effective output format and jq filter from flags/config.
+ * - Building the runtime context object passed to command implementations.
+ * - Enforcing risk-level policy.
+ * - Running dry-run previews and confirmation prompts.
+ *
+ * These functions are called from both the runner adapter and help/schema
+ * generators, so they carry no side-effects beyond argument validation.
+ */
+import { normalizeLegacyOutputFormat, riskLevelOrder } from "./types.js";
+/**
+ * Extracts the `--jq` flag value from parsed flags.
+ *
+ * @param flags - Parsed flag map.
+ * @returns Trimmed jq expression, or `undefined` if absent / blank.
+ *
+ * @example
+ * ```ts
+ * const jq = resolveJqFilter(flags); // ".[].name" | undefined
+ * ```
+ */
+export function resolveJqFilter(flags) {
+    const v = flags.jq;
+    if (v === undefined || v === null)
+        return undefined;
+    const s = String(v).trim();
+    return s === "" ? undefined : s;
+}
+/**
+ * Resolves the effective output format from the cascade:
+ * CLI flag → global config default → command default → `"compress"`.
+ *
+ * @param options - Resolution options.
+ * @returns The effective output format.
+ */
+export function resolveFormat({ flags, def, configDefault, }) {
+    if (def.hasFormat === false)
+        return "pretty";
+    const fromFlag = normalizeLegacyOutputFormat(flags.format);
+    if (fromFlag)
+        return fromFlag;
+    const fromConfig = normalizeLegacyOutputFormat(configDefault);
+    if (fromConfig)
+        return fromConfig;
+    const fromDef = normalizeLegacyOutputFormat(def.defaultOutputFormat);
+    if (fromDef)
+        return fromDef;
+    return "compress";
+}
+/**
+ * Resolves both the output format and jq filter, and validates that `--jq`
+ * is only used with `json` or `compress` formats.
+ *
+ * @param options - Resolution options.
+ * @returns Resolved format and jq filter.
+ * @throws Error with code `"validation_error"` if `--jq` is used with an incompatible format.
+ */
+export function resolveOutputConfig(options) {
+    let format = resolveFormat(options);
+    const jqFilter = resolveJqFilter(options.flags);
+    if (jqFilter && format === "pretty") {
+        format = "json";
+    }
+    if (jqFilter && format !== "json" && format !== "compress") {
+        throw new Error(`--jq only applies with --format json or --format compress (current: ${format}).`);
+    }
+    return { format, jqFilter };
+}
+/**
+ * Asserts that the command's risk level does not exceed the configured ceiling.
+ *
+ * The comparison uses {@link riskLevelOrder}: `high-risk-write (2) > write (1) > read (0)`.
+ *
+ * @param options - Assertion options.
+ * @throws The error returned by `options.createError` when the ceiling is exceeded.
+ *
+ * @example
+ * ```ts
+ * assertRiskWithinLevel({
+ *   commandLabel: "app delete",
+ *   commandRisk: "high-risk-write",
+ *   configuredRiskLevel: "write",
+ *   nonInteractive: true,
+ *   createError: (msg) => cliErrors.validation(msg),
+ * });
+ * ```
+ */
+export function assertRiskWithinLevel(options) {
+    if (!options.configuredRiskLevel)
+        return;
+    if (options.skipWhenDryRun && options.dryRun)
+        return;
+    if (riskLevelOrder(options.commandRisk) <= riskLevelOrder(options.configuredRiskLevel)) {
+        return;
+    }
+    const detail = options.nonInteractive
+        ? `Command \`${options.commandLabel}\` has risk level "${options.commandRisk}", which exceeds the configured riskLevel "${options.configuredRiskLevel}".`
+        : `Command \`${options.commandLabel}\` has risk level "${options.commandRisk}", which exceeds the configured riskLevel "${options.configuredRiskLevel}".\n` +
+            `  Edit the config file manually and set riskLevel to "${options.commandRisk}". Visit https://qizhiyuntu.feishu.cn/docx/JTiOdxQlXo2dQLxXVu6ctutcnme for more information.`;
+    options.onViolation?.(detail);
+    throw options.createError(detail);
+}
+/**
+ * Constructs the {@link RuntimeContext} object passed to every command's
+ * `validate`, `dryRun`, and `execute` function.
+ *
+ * The context provides:
+ * - Typed accessors for flags (`str`, `bool`, `num`, `flag`).
+ * - Positional argument accessors (`arg`).
+ * - The `output()` method for rendering results through the formatter.
+ *
+ * @template Extras - Shape of the adapter-supplied extras object.
+ * @param opts     - Construction options.
+ * @returns A fully populated runtime context object.
+ */
+export function buildRuntimeContext(opts) {
+    const { flags, def } = opts;
+    const argIndexByName = new Map((def.args ?? []).map((arg, index) => [arg.name, index]));
+    return {
+        rawFlags: flags,
+        format: opts.format,
+        nonInteractive: opts.nonInteractive,
+        args: opts.args,
+        ...(opts.extras ?? {}),
+        arg(nameOrIndex, defaultVal) {
+            const index = typeof nameOrIndex === "number"
+                ? nameOrIndex
+                : argIndexByName.get(nameOrIndex) ?? -1;
+            const value = index >= 0 ? opts.args[index] : undefined;
+            return value ?? defaultVal ?? "";
+        },
+        str(name) {
+            return String(flags[name] ?? "");
+        },
+        bool(name) {
+            if (flags[name] === true)
+                return true;
+            return opts.defaults?.booleans?.[name] === true;
+        },
+        num(name, defaultVal) {
+            const v = flags[name];
+            if (typeof v === "number")
+                return v;
+            const configuredDefault = opts.defaults?.numbers?.[name];
+            if (configuredDefault != null)
+                return configuredDefault;
+            return defaultVal ?? 0;
+        },
+        flag(name) {
+            return flags[name];
+        },
+        output(result) {
+            opts.formatOutput(result, {
+                command: opts.commandLabel,
+                risk: def.risk,
+                format: opts.format,
+                jqFilter: opts.jqFilter,
+            });
+        },
+    };
+}
+/**
+ * Checks whether `--dry-run` was supplied and, if so, calls the command's
+ * `dryRun` hook and outputs the preview.
+ *
+ * @param options - Dry-run options.
+ * @returns `true` if dry-run was handled (caller should return early);
+ *          `false` if `--dry-run` was not present.
+ * @throws The error from `createUnsupportedError` when `--dry-run` is used
+ *         on a command without a `dryRun` hook.
+ */
+export async function runDryRunIfNeeded(options) {
+    if (!options.flags["dry-run"])
+        return false;
+    if (!options.def.dryRun) {
+        throw options.createUnsupportedError(`--dry-run is not supported for \`${options.commandLabel}\`.`);
+    }
+    let preview;
+    try {
+        preview = await options.def.dryRun(options.ctx);
+    }
+    catch (error) {
+        if (options.mapError) {
+            throw options.mapError(error);
+        }
+        throw error;
+    }
+    options.formatOutput({ ok: true, data: preview }, {
+        command: options.commandLabel,
+        risk: options.def.risk,
+        format: options.format,
+        dryRun: true,
+        jqFilter: options.jqFilter,
+    });
+    return true;
+}
+/**
+ * Displays an interactive confirmation prompt on stderr and resolves
+ * when the user types `y` or `yes` (case-insensitive).
+ *
+ * - Any other answer throws a `"cancelled"` error.
+ * - Ctrl+C (SIGINT) also throws a `"cancelled"` error without a stack trace.
+ *
+ * @param options - Prompt options.
+ * @returns Resolves normally on confirmation.
+ * @throws The error from `createCancelledError` on decline or Ctrl+C.
+ *
+ * @example
+ * ```ts
+ * await requireConfirmationPrompt({
+ *   lines: ["This will permanently delete the dataset.", "Are you sure? (y/N)"],
+ *   createCancelledError: (msg) => cliErrors.cancelled(msg),
+ * });
+ * ```
+ */
+export async function requireConfirmationPrompt(options) {
+    const readline = await import("node:readline");
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stderr,
+    });
+    return new Promise((resolve, reject) => {
+        rl.on("SIGINT", () => {
+            rl.close();
+            reject(options.createCancelledError("Operation cancelled by user."));
+        });
+        rl.question(options.lines.join("\n"), (answer) => {
+            rl.close();
+            if (answer.toLowerCase() === "y" || answer.toLowerCase() === "yes") {
+                resolve();
+            }
+            else {
+                reject(options.createCancelledError("Operation cancelled by user."));
+            }
+        });
+    });
+}

package/lib/framework/runner.d.ts

@@ -0,0 +1,246 @@
+/**
+ * @fileoverview Command execution engine — the core runner.
+ *
+ * {@link runCommandWithAdapter} is the central orchestration function that
+ * drives every declarative command through the following pipeline:
+ *
+ * ```
+ * parseFlags → validateFlags → validateArgs → assertRiskWithinLevel
+ *   → prepare (adapter) → resolveOutputConfig → buildRuntimeContext
+ *   → validate (command hook) → runDryRunIfNeeded → confirmHighRisk (adapter)
+ *   → execute (command) → formatOutput (adapter)
+ * ```
+ *
+ * The adapter encapsulates CLI-specific concerns (auth, config, confirmation UI)
+ * so the runner itself remains framework-only and testable.
+ */
+import type { CliErrorsShape } from "../errors.js";
+import { type ParsedFlags } from "./flags.js";
+import type { CommandDefinition, CommandResult, FlagDef, OutputFormat, Risk, RuntimeContext } from "./types.js";
+/**
+ * Raw environment values supplied by the CLI entry point before any
+ * processing occurs. These come directly from the meow/yargs/commander
+ * parsed input and the loaded config file.
+ */
+export interface RunnerEnvBase {
+    /** Raw parsed flags (string-keyed, untyped). */
+    rawFlags: Record<string, any>;
+    /**
+     * `true` when stdin is not a TTY, or when a confirmation flag
+     * (`--yes` / `-y`) was explicitly supplied.
+     */
+    isNonInteractive: boolean;
+    /**
+     * Default output format sourced from the config file.
+     * Falls through when neither the CLI flag nor command default is set.
+     */
+    defaultFormat?: OutputFormat;
+    /**
+     * User-configured risk ceiling from the config file.
+     * Commands whose risk exceeds this are blocked in non-interactive mode.
+     */
+    riskLevel?: Risk;
+    /**
+     * Positional arguments after the subcommand name.
+     */
+    args?: string[];
+}
+/**
+ * Values produced by the adapter's `prepare` hook and merged into the
+ * runtime context. Allows the adapter to inject dependencies
+ * (e.g. `appCode`, `session`, `config`) without the runner knowing
+ * about them.
+ *
+ * @template CtxExtras - Shape of the extras object merged into the context.
+ */
+export interface PreparedRuntimeValues<CtxExtras extends object = {}> {
+    /**
+     * Static defaults for boolean and number flags that should take effect
+     * even when the flag was not explicitly provided.
+     */
+    defaults?: {
+        booleans?: Record<string, boolean | undefined>;
+        numbers?: Record<string, number | undefined>;
+    };
+    /**
+     * Additional context properties merged into {@link RuntimeContext}.
+     */
+    extras?: CtxExtras;
+}
+/**
+ * Risk policy that governs how the runner handles the configured risk ceiling.
+ *
+ * @template Env - Concrete runner environment type.
+ */
+export interface RiskPolicy<Env extends RunnerEnvBase> {
+    /**
+     * When `true`, the risk ceiling check is skipped during dry-run.
+     * @default false
+     */
+    skipWhenDryRun?: boolean;
+    /**
+     * Side-effect callback invoked with the violation message before throwing.
+     * Use for logging, telemetry, or user-facing warnings.
+     */
+    onViolation?: (message: string, params: {
+        def: CommandDefinition;
+        env: Env;
+        flags: ParsedFlags;
+    }) => void;
+    /**
+     * Factory that creates the error to throw when a risk violation occurs.
+     * Typically produces a {@link CliError} with code `"validation_error"`.
+     */
+    createError: (message: string, params: {
+        def: CommandDefinition;
+        env: Env;
+        flags: ParsedFlags;
+    }) => unknown;
+}
+/** Options for the adapter's `confirmHighRisk` method. */
+export interface ConfirmHighRiskOptions<Env extends RunnerEnvBase> {
+    /** Command definition being executed. */
+    def: CommandDefinition;
+    /** Runner environment. */
+    env: Env;
+    /** Parsed flags. */
+    flags: ParsedFlags;
+    /** Human-readable command label. */
+    commandLabel: string;
+}
+/**
+ * Context object passed to every hook on the runner adapter.
+ * Contains the command definition, environment, parsed flags,
+ * and the already-constructed runtime context.
+ *
+ * @template Env      - Concrete runner environment type.
+ * @template CtxExtras - Shape of the adapter extras.
+ */
+export interface ExecuteHookOptions<Env extends RunnerEnvBase, CtxExtras extends object = {}> {
+    /** Command definition. */
+    def: CommandDefinition<any>;
+    /** Runner environment. */
+    env: Env;
+    /** Parsed flags. */
+    flags: ParsedFlags;
+    /** Fully constructed runtime context. */
+    ctx: RuntimeContext<CtxExtras>;
+    /** Human-readable command label. */
+    commandLabel: string;
+}
+/**
+ * Extended hook options passed to the `finalize` hook, which additionally
+ * receives the command result and any thrown error.
+ *
+ * @template Env      - Concrete runner environment type.
+ * @template CtxExtras - Shape of the adapter extras.
+ */
+export interface FinalizeHookOptions<Env extends RunnerEnvBase, CtxExtras extends object = {}> extends ExecuteHookOptions<Env, CtxExtras> {
+    /** Command result if `execute` completed successfully. */
+    result?: CommandResult;
+    /** Error thrown by `execute`, or `undefined` on success. */
+    error?: unknown;
+}
+/**
+ * Adapter interface that bridges the framework runner with a concrete CLI.
+ *
+ * Implementations (one per CLI binary) provide:
+ * - Error factory with CLI-specific error codes.
+ * - Global/pipeline flag definitions.
+ * - `prepare` hook for dependency injection.
+ * - `confirmHighRisk` for interactive prompts.
+ * - `formatOutput` for rendering results.
+ *
+ * @template Env       - Concrete environment type supplied by the CLI entry point.
+ * @template CtxExtras - Shape of the extras object injected by `prepare`.
+ */
+export interface RunnerAdapter<Env extends RunnerEnvBase, CtxExtras extends object = {}> {
+    /** Error factory for runner-issued errors. */
+    cliErrors: Pick<CliErrorsShape, "flagMissing" | "validation" | "cancelled">;
+    /**
+     * Global flag definitions prepended to every command's flag list.
+     * Examples: `--env`, `--appcode`, `--global`.
+     */
+    pipelineFlags?: FlagDef[];
+    /**
+     * Renders a {@link CommandResult} to stdout/stderr.
+     * Receives the resolved format and jq filter so it does not need to
+     * resolve them again.
+     */
+    formatOutput: <T>(result: CommandResult<T>, options: {
+        command: string;
+        risk: CommandDefinition["risk"];
+        format: OutputFormat;
+        dryRun?: boolean;
+        jqFilter?: string;
+    }) => void;
+    /**
+     * Produces the full command label string for error messages and envelopes.
+     * Example: `"dataset list"` for `rabetbase dataset list`.
+     */
+    getCommandLabel: (def: CommandDefinition, env: Env) => string;
+    /**
+     * Prepares the runtime extras and defaults by inspecting the environment
+     * and parsed flags. Called after flag validation but before context building.
+     *
+     * Typical responsibilities:
+     * - Resolve and validate `appCode`.
+     * - Load or refresh session cookie.
+     * - Merge config file with flags.
+     */
+    prepare: (def: CommandDefinition<any>, env: Env, flags: ParsedFlags, commandLabel: string) => Promise<PreparedRuntimeValues<CtxExtras>>;
+    /**
+     * Prompts the user for confirmation when executing a `high-risk-write`
+     * command without `--yes`. The adapter decides how to prompt
+     * (readline, inquirer, etc.) and throws a `cancelled` error on decline.
+     */
+    confirmHighRisk: (options: ConfirmHighRiskOptions<Env>) => Promise<void>;
+    /** Risk policy governing how the runner handles risk ceiling violations. */
+    riskPolicy: RiskPolicy<Env>;
+    /**
+     * Optional error mapper applied to errors thrown by the `dryRun` hook.
+     * Allows the adapter to normalize framework errors to its own types.
+     */
+    mapDryRunError?: (error: unknown, options: ExecuteHookOptions<Env, CtxExtras>) => unknown;
+    /**
+     * Optional error mapper applied to errors thrown by `execute`.
+     * Allows the adapter to catch and re-throw with additional context.
+     */
+    mapExecuteError?: (error: unknown, options: ExecuteHookOptions<Env, CtxExtras>) => unknown;
+    /**
+     * Optional cleanup hook called in a `finally` block after execution
+     * (whether `execute` succeeded or threw). Suitable for:
+     * - Revoking / refreshing session cookies.
+     * - Flushing telemetry spans.
+     * - Closing database connections.
+     */
+    finalize?: (options: FinalizeHookOptions<Env, CtxExtras>) => Promise<void>;
+}
+/**
+ * Orchestrates the full command lifecycle using an adapter for CLI-specific concerns.
+ *
+ * Pipeline order:
+ * 1. Merge pipeline flags with command flags via {@link mergeFlagDefs}.
+ * 2. {@link parseFlags} and {@link validateFlags}.
+ * 3. {@link validateArgs} for required positional arguments.
+ * 4. {@link assertRiskWithinLevel} using the adapter's risk policy.
+ * 5. `adapter.prepare(...)` to resolve dependencies.
+ * 6. {@link resolveOutputConfig} for format and jq.
+ * 7. {@link buildRuntimeContext} to construct the context object.
+ * 8. `def.validate(ctx)` — business-level validation.
+ * 9. {@link runDryRunIfNeeded} — dry-run preview if `--dry-run`.
+ * 10. `adapter.confirmHighRisk(...)` — high-risk-write confirmation if needed.
+ * 11. `def.execute(ctx)` — command implementation.
+ * 12. `adapter.formatOutput(result, ...)` — render to stdout.
+ *
+ * On error, the thrown error (after optional mapping) propagates to the
+ * caller's `handleErrorAsync` / try-catch wrapper.
+ *
+ * @template Env       - Concrete environment type.
+ * @template CtxExtras - Shape of the adapter extras.
+ * @param def     - Command definition to execute.
+ * @param env     - Runner environment from the CLI entry point.
+ * @param adapter - Adapter bridging to the concrete CLI implementation.
+ * @returns Resolves on success; throws on any failure.
+ */
+export declare function runCommandWithAdapter<Env extends RunnerEnvBase, CtxExtras extends object = {}>(def: CommandDefinition<any>, env: Env, adapter: RunnerAdapter<Env, CtxExtras>): Promise<void>;

package/lib/framework/runner.js

@@ -0,0 +1,184 @@
+/**
+ * @fileoverview Command execution engine — the core runner.
+ *
+ * {@link runCommandWithAdapter} is the central orchestration function that
+ * drives every declarative command through the following pipeline:
+ *
+ * ```
+ * parseFlags → validateFlags → validateArgs → assertRiskWithinLevel
+ *   → prepare (adapter) → resolveOutputConfig → buildRuntimeContext
+ *   → validate (command hook) → runDryRunIfNeeded → confirmHighRisk (adapter)
+ *   → execute (command) → formatOutput (adapter)
+ * ```
+ *
+ * The adapter encapsulates CLI-specific concerns (auth, config, confirmation UI)
+ * so the runner itself remains framework-only and testable.
+ */
+import { createFlagHelpers } from "./flags.js";
+import { assertRiskWithinLevel, buildRuntimeContext, resolveOutputConfig, runDryRunIfNeeded, } from "./runner-shared.js";
+/**
+ * Orchestrates the full command lifecycle using an adapter for CLI-specific concerns.
+ *
+ * Pipeline order:
+ * 1. Merge pipeline flags with command flags via {@link mergeFlagDefs}.
+ * 2. {@link parseFlags} and {@link validateFlags}.
+ * 3. {@link validateArgs} for required positional arguments.
+ * 4. {@link assertRiskWithinLevel} using the adapter's risk policy.
+ * 5. `adapter.prepare(...)` to resolve dependencies.
+ * 6. {@link resolveOutputConfig} for format and jq.
+ * 7. {@link buildRuntimeContext} to construct the context object.
+ * 8. `def.validate(ctx)` — business-level validation.
+ * 9. {@link runDryRunIfNeeded} — dry-run preview if `--dry-run`.
+ * 10. `adapter.confirmHighRisk(...)` — high-risk-write confirmation if needed.
+ * 11. `def.execute(ctx)` — command implementation.
+ * 12. `adapter.formatOutput(result, ...)` — render to stdout.
+ *
+ * On error, the thrown error (after optional mapping) propagates to the
+ * caller's `handleErrorAsync` / try-catch wrapper.
+ *
+ * @template Env       - Concrete environment type.
+ * @template CtxExtras - Shape of the adapter extras.
+ * @param def     - Command definition to execute.
+ * @param env     - Runner environment from the CLI entry point.
+ * @param adapter - Adapter bridging to the concrete CLI implementation.
+ * @returns Resolves on success; throws on any failure.
+ */
+export async function runCommandWithAdapter(def, env, adapter) {
+    const commandLabel = adapter.getCommandLabel(def, env);
+    const { parseFlags, validateFlags } = createFlagHelpers(adapter.cliErrors);
+    const allFlagDefs = mergeFlagDefs(adapter.pipelineFlags ?? [], def.flags);
+    const flags = parseFlags(allFlagDefs, env.rawFlags);
+    validateFlags(allFlagDefs, flags, commandLabel);
+    validateArgs(def, env.args ?? [], adapter.cliErrors, commandLabel);
+    assertRiskWithinLevel({
+        commandLabel,
+        commandRisk: def.risk,
+        configuredRiskLevel: env.riskLevel,
+        nonInteractive: env.isNonInteractive,
+        dryRun: flags["dry-run"] === true,
+        skipWhenDryRun: adapter.riskPolicy.skipWhenDryRun,
+        onViolation: (message) => adapter.riskPolicy.onViolation?.(message, { def, env, flags }),
+        createError: (message) => adapter.riskPolicy.createError(message, { def, env, flags }),
+    });
+    const prepared = await adapter.prepare(def, env, flags, commandLabel);
+    let format;
+    let jqFilter;
+    try {
+        ({ format, jqFilter } = resolveOutputConfig({
+            flags,
+            def,
+            configDefault: env.defaultFormat,
+        }));
+    }
+    catch (error) {
+        throw adapter.cliErrors.validation(error instanceof Error ? error.message : String(error));
+    }
+    const ctx = buildRuntimeContext({
+        commandLabel,
+        format,
+        jqFilter,
+        flags,
+        def,
+        nonInteractive: env.isNonInteractive,
+        args: env.args ?? [],
+        defaults: prepared.defaults,
+        extras: prepared.extras,
+        formatOutput: adapter.formatOutput,
+    });
+    if (def.validate) {
+        await def.validate(ctx);
+    }
+    const executeOptions = {
+        def,
+        env,
+        flags,
+        ctx,
+        commandLabel,
+    };
+    if (await runDryRunIfNeeded({
+        flags,
+        def,
+        ctx,
+        commandLabel,
+        format,
+        jqFilter,
+        formatOutput: adapter.formatOutput,
+        createUnsupportedError: (message) => adapter.cliErrors.validation(message),
+        mapError: adapter.mapDryRunError
+            ? (error) => adapter.mapDryRunError(error, executeOptions)
+            : undefined,
+    })) {
+        return;
+    }
+    if (def.risk === "high-risk-write" && !flags.yes) {
+        await adapter.confirmHighRisk({
+            def,
+            env,
+            flags,
+            commandLabel,
+        });
+    }
+    let result;
+    let thrown;
+    try {
+        result = await def.execute(ctx);
+    }
+    catch (error) {
+        thrown = adapter.mapExecuteError
+            ? adapter.mapExecuteError(error, executeOptions)
+            : error;
+    }
+    finally {
+        if (adapter.finalize) {
+            await adapter.finalize({
+                ...executeOptions,
+                result,
+                error: thrown,
+            });
+        }
+    }
+    if (thrown) {
+        throw thrown;
+    }
+    adapter.formatOutput(result, {
+        command: commandLabel,
+        risk: def.risk,
+        format,
+        jqFilter,
+    });
+}
+/**
+ * Merges pipeline (global) flags with command-specific flags.
+ * Command flags take precedence over pipeline flags of the same name.
+ *
+ * @param base    - Pipeline/global flag definitions.
+ * @param command - Command-specific flag definitions.
+ * @returns Merged flag list (command overrides pipeline).
+ */
+function mergeFlagDefs(base, command) {
+    const merged = new Map();
+    for (const def of [...base, ...command]) {
+        merged.set(def.name, def);
+    }
+    return [...merged.values()];
+}
+/**
+ * Validates that all required positional arguments are present.
+ *
+ * @param def           - Command definition whose args are checked.
+ * @param args          - Actual positional arguments from the CLI.
+ * @param cliErrors     - Error factory.
+ * @param commandLabel  - Human-readable command label for error messages.
+ * @throws {@link CliError} with code `"validation_error"` for the first missing required arg.
+ */
+function validateArgs(def, args, cliErrors, commandLabel) {
+    for (const [index, argDef] of (def.args ?? []).entries()) {
+        if (argDef.required === false) {
+            continue;
+        }
+        const value = args[index];
+        if (value === undefined || value === "") {
+            throw cliErrors.validation(`Validation error: Missing required argument: <${argDef.name}> for \`${commandLabel}\`.`);
+        }
+    }
+}