@lovrabet/cli-framework 0.1.1-beta.0

package/lib/framework/flags.js

@@ -0,0 +1,152 @@
+/**
+ * @fileoverview Flag parsing and validation helpers.
+ *
+ * Provides the {@link createFlagHelpers} factory which returns `parseFlags`
+ * and `validateFlags` — the two-phase pipeline used by the runner adapter.
+ *
+ * Phase 1 (`parseFlags`): coerce raw CLI inputs into typed values using
+ * {@link FlagDef} metadata.
+ *
+ * Phase 2 (`validateFlags`): enforce `required`, `enum`, and `pattern`
+ * constraints and throw typed {@link CliError} on violation.
+ */
+/**
+ * Creates a paired set of flag helpers used by the framework runner.
+ *
+ * @param cliErrors - Subset of the error factory providing `flagMissing` and `validation`.
+ * @returns An object with `parseFlags` and `validateFlags` functions.
+ *
+ * @example
+ * ```ts
+ * const { parseFlags, validateFlags } = createFlagHelpers(cliErrors);
+ * const flags = parseFlags(flagDefs, rawInput);
+ * validateFlags(flagDefs, flags, "api list");
+ * ```
+ */
+export function createFlagHelpers(cliErrors) {
+    /**
+     * Phase 1 — converts raw flag values (from meow / yargs / raw object) into
+     * their declared types using the definitions in `defs`.
+     *
+     * - Boolean flags: `true` when the raw value is `true` or `"true"`.
+     * - Number flags: coerces via `Number()`; throws on `NaN`.
+     * - String flags: all other values stringified.
+     * - Unset flags with a `default` are populated automatically.
+     *
+     * @param defs      - Ordered list of flag definitions.
+     * @param rawFlags  - Raw key-value map from the CLI parser.
+     * @returns A {@link ParsedFlags} map with all defined flags present.
+     */
+    function parseFlags(defs, rawFlags) {
+        const result = {};
+        for (const def of defs) {
+            const raw = getRawFlagValue(def, rawFlags);
+            if (raw === undefined || raw === null) {
+                if (def.default !== undefined) {
+                    result[def.name] = def.default;
+                }
+                continue;
+            }
+            result[def.name] = coerce(def, raw, cliErrors);
+        }
+        return result;
+    }
+    /**
+     * Phase 2 — validates a set of parsed flags against their definitions.
+     * Throws a typed {@link CliError} for the first violation encountered.
+     *
+     * Checks (in order):
+     * 1. **Required** — throws `flagMissing` if a required flag is absent or empty.
+     * 2. **Enum** — throws `validation` if the value is not in the allowed list.
+     * 3. **Pattern** — throws `validation` if the regex does not match.
+     *
+     * @param defs         - Ordered list of flag definitions.
+     * @param parsed       - Result of {@link parseFlags}.
+     * @param commandLabel - Human-readable command label used in error messages.
+     * @throws {@link CliError} on the first validation failure.
+     */
+    function validateFlags(defs, parsed, commandLabel) {
+        for (const def of defs) {
+            const val = parsed[def.name];
+            if (def.required && (val === undefined || val === "")) {
+                throw cliErrors.flagMissing(def.name, `--${def.name} is required for \`${commandLabel}\`.`);
+            }
+            if (def.enum && def.enum.length > 0 && val !== undefined && val !== "") {
+                if (!def.enum.includes(String(val))) {
+                    throw cliErrors.validation(`Invalid value "${val}" for --${def.name}. Allowed: ${def.enum.join(", ")}`);
+                }
+            }
+            if (def.pattern && val !== undefined && val !== "") {
+                if (!def.pattern.regex.test(String(val))) {
+                    throw cliErrors.validation(`Invalid --${def.name}: expected ${def.pattern.description}, got "${val}".`);
+                }
+            }
+        }
+    }
+    return { parseFlags, validateFlags };
+}
+/**
+ * Looks up a raw flag value by trying multiple name variants.
+ * Checks, in order: `def.name`, camelCase of `def.name`, `def.alias`,
+ * camelCase of `def.alias`.
+ *
+ * @param def       - Flag definition providing name and optional alias.
+ * @param rawFlags  - Raw key-value map from the CLI parser.
+ * @returns The first matching raw value, or `undefined`.
+ */
+function getRawFlagValue(def, rawFlags) {
+    const candidates = [
+        def.name,
+        toCamelCase(def.name),
+        def.alias,
+        def.alias ? toCamelCase(def.alias) : undefined,
+    ];
+    for (const candidate of candidates) {
+        if (!candidate)
+            continue;
+        const raw = rawFlags[candidate];
+        if (raw !== undefined && raw !== null) {
+            return raw;
+        }
+    }
+    return undefined;
+}
+/**
+ * Coerces a raw flag value to the type declared in `def`.
+ *
+ * @param def       - Flag definition specifying the target type.
+ * @param raw       - Raw value from the CLI parser.
+ * @param cliErrors - Error factory for throwing on invalid number input.
+ * @returns The coerced typed value.
+ * @throws {@link CliError} with code `"validation_error"` if a number flag
+ *         receives a non-numeric value.
+ */
+function coerce(def, raw, cliErrors) {
+    switch (def.type) {
+        case "boolean":
+            return raw === true || raw === "true";
+        case "number": {
+            const n = Number(raw);
+            if (Number.isNaN(n)) {
+                throw cliErrors.validation(`--${def.name} expects a number, got "${raw}"`);
+            }
+            return n;
+        }
+        default:
+            return String(raw);
+    }
+}
+/**
+ * Converts a kebab-case string to camelCase.
+ *
+ * @param s - Input string, e.g. `"dry-run"`.
+ * @returns camelCase equivalent, e.g. `"dryRun"`.
+ *
+ * @example
+ * ```ts
+ * toCamelCase("app-code") // "appCode"
+ * ```
+ */
+function toCamelCase(s) {
+    return s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}

package/lib/framework/help.d.ts

@@ -0,0 +1,136 @@
+/**
+ * @fileoverview Help text generation for the CLI.
+ *
+ * Produces structured plain-text help for:
+ * - Single commands (`<service> <command> --help`)
+ * - Entire services (`<service> --help`)
+ * - Full CLI overview (`--help`)
+ *
+ * All output follows the same section-based layout (USAGE / FLAGS / ARGS etc.)
+ * so callers can compose consistent help strings without reimplementing formatting.
+ */
+import type { CommandDefinition, FlagDef } from "./types.js";
+/**
+ * A global (top-level) flag definition used in the main `--help` output.
+ */
+export interface GlobalHelpFlag {
+    /** Flag name (without leading `--`). */
+    name: string;
+    /** Value type. */
+    type: "string" | "boolean";
+    /** Description shown in the GLOBAL OPTIONS block. */
+    description: string;
+    /**
+     * Short hint appended to the flag name in the usage line
+     * (e.g. `<env>` for `--env daily`).
+     */
+    hint?: string;
+    /**
+     * When `true`, the flag is omitted from the help text.
+     */
+    hidden?: boolean;
+}
+/**
+ * A command summary entry in a service's command list.
+ */
+export interface HelpCommandListing {
+    /** Subcommand name (e.g. `"list"`). */
+    command: string;
+    /** One-line description. */
+    description: string;
+    /**
+     * Optional tag appended to the command name in listings
+     * (e.g. `"  beta"`).
+     */
+    tag?: string;
+}
+/**
+ * A service entry used to render service-level and full CLI help.
+ */
+export interface HelpServiceEntry {
+    /** Service name as used in the CLI (e.g. `"api"`). */
+    service: string;
+    /** Display label shown in help headings (e.g. `"API"`). */
+    label: string;
+    /** Flat list of subcommand listings. */
+    commands: HelpCommandListing[];
+    /**
+     * For single-command services, the name of the default subcommand
+     * (which is omitted from the invocation path).
+     */
+    defaultCommand?: string;
+    /**
+     * `true` when `service === command` for this service — the whole
+     * service acts as a single command with no subcommands.
+     */
+    isSingleCommand?: boolean;
+    /**
+     * Present when the service supports a wildcard command pattern
+     * (e.g. `<script>` for `codegen <script>`).
+     */
+    wildcardDef?: CommandDefinition;
+}
+/**
+ * Dependencies required by {@link createHelpGenerators}.
+ */
+export interface HelpGeneratorOptions {
+    /** CLI binary name (e.g. `"rabetbase"`). Used in usage strings. */
+    cliBinName: string;
+    /** Display name shown in the full help header (e.g. `"Rabetbase CLI"`). */
+    cliDisplayName: string;
+    /** Global flags to list under GLOBAL OPTIONS. */
+    globalFlags: GlobalHelpFlag[];
+    /** All registered service entries. */
+    serviceRegistry: HelpServiceEntry[];
+    /**
+     * Resolves a {@link HelpServiceEntry} by service name, or `undefined`
+     * if the service does not exist.
+     */
+    getServiceEntry(service: string): HelpServiceEntry | undefined;
+    /**
+     * Resolves the ordered array of {@link CommandDefinition} objects for
+     * a given service, or `undefined` if the service has no definitions.
+     */
+    getServiceDefinitions(service: string): CommandDefinition[] | undefined;
+    /**
+     * Function that builds the complete effective flag list for a command.
+     * Passed in so the help generator can display the correct flag set
+     * without re-implementing the built-in flag injection logic.
+     */
+    buildAllFlags(def: CommandDefinition): FlagDef[];
+    /**
+     * Text shown as a prerequisite hint for commands that require an app-code.
+     * Used in the PREREQUISITES section.
+     */
+    appPrerequisiteText: string;
+    /**
+     * Suffix appended to the service usage line (e.g. `" [--env <env>]"`).
+     */
+    serviceUsageSuffix?: string;
+    /**
+     * When `true`, the `helpExtra` content of wildcard definitions is
+     * included in the full help output.
+     * @default false
+     */
+    includeWildcardExtraInFullHelp?: boolean;
+}
+/**
+ * Creates a set of help generators for commands, services, and the full CLI.
+ *
+ * @param options - Resolver functions and metadata needed to render help.
+ * @returns An object with `generateCommandHelp`, `generateServiceHelp`,
+ *          and `generateFullHelp`.
+ *
+ * @example
+ * ```ts
+ * const { generateCommandHelp } = createHelpGenerators({
+ *   // ... options
+ * });
+ * console.log(generateCommandHelp(someCommandDef));
+ * ```
+ */
+export declare function createHelpGenerators(options: HelpGeneratorOptions): {
+    generateCommandHelp: (def: CommandDefinition) => string;
+    generateServiceHelp: (service: string) => string;
+    generateFullHelp: () => string;
+};

package/lib/framework/help.js

@@ -0,0 +1,244 @@
+/**
+ * @fileoverview Help text generation for the CLI.
+ *
+ * Produces structured plain-text help for:
+ * - Single commands (`<service> <command> --help`)
+ * - Entire services (`<service> --help`)
+ * - Full CLI overview (`--help`)
+ *
+ * All output follows the same section-based layout (USAGE / FLAGS / ARGS etc.)
+ * so callers can compose consistent help strings without reimplementing formatting.
+ */
+/**
+ * Creates a set of help generators for commands, services, and the full CLI.
+ *
+ * @param options - Resolver functions and metadata needed to render help.
+ * @returns An object with `generateCommandHelp`, `generateServiceHelp`,
+ *          and `generateFullHelp`.
+ *
+ * @example
+ * ```ts
+ * const { generateCommandHelp } = createHelpGenerators({
+ *   // ... options
+ * });
+ * console.log(generateCommandHelp(someCommandDef));
+ * ```
+ */
+export function createHelpGenerators(options) {
+    /**
+     * Generates the full help text for a single command.
+     * Includes: description, usage, risk level, arguments, flags, and prerequisites.
+     *
+     * @param def - Command definition.
+     * @returns A formatted plain-text help string.
+     */
+    function generateCommandHelp(def) {
+        const lines = [];
+        const entry = options.getServiceEntry(def.service);
+        const cmd = entry?.isSingleCommand && entry.defaultCommand === def.command
+            ? `${options.cliBinName} ${def.service}`
+            : def.service === def.command
+                ? `${options.cliBinName} ${def.service}`
+                : `${options.cliBinName} ${def.service} ${def.command}`;
+        const argsSig = def.args
+            ? def.args.map((a) => (a.required !== false ? `<${a.name}>` : `[${a.name}]`)).join(" ")
+            : "";
+        const usageSig = argsSig ? `${cmd} ${argsSig} [flags]` : `${cmd} [flags]`;
+        lines.push("");
+        lines.push(`  ${def.description}`);
+        lines.push("");
+        lines.push("  USAGE");
+        lines.push(`    ${usageSig}`);
+        lines.push("");
+        lines.push(`  RISK: ${def.risk}`);
+        if (def.risk === "high-risk-write") {
+            lines.push("    Requires --yes to confirm, or interactive prompt.");
+        }
+        lines.push("");
+        if (def.args && def.args.length > 0) {
+            lines.push("  ARGS");
+            const maxArgName = Math.max(...def.args.map((a) => a.name.length + 2));
+            for (const a of def.args) {
+                const label = `<${a.name}>`.padEnd(maxArgName + 2);
+                const req = a.required !== false ? " (required)" : "";
+                lines.push(`    ${label}${a.description}${req}`);
+            }
+            lines.push("");
+        }
+        if (def.flags.length > 0 || def.dryRun || def.hasFormat !== false) {
+            const visibleFlags = options.buildAllFlags(def).filter((f) => !f.hidden);
+            if (visibleFlags.length > 0) {
+                lines.push("  FLAGS");
+                const maxName = Math.max(...visibleFlags.map((f) => formatFlagName(f).length));
+                for (const fl of visibleFlags) {
+                    lines.push(`    ${formatFlagName(fl).padEnd(maxName + 2)}${renderFlagDesc(fl)}`);
+                }
+                lines.push("");
+            }
+        }
+        const hints = [];
+        if (def.requiresAuth !== false) {
+            hints.push(`Requires authentication (run \`${options.cliBinName} auth\` first).`);
+        }
+        if (def.requiresAppCode !== false) {
+            hints.push(options.appPrerequisiteText);
+        }
+        if (hints.length > 0) {
+            lines.push("  PREREQUISITES");
+            for (const h of hints) {
+                lines.push(`    • ${h}`);
+            }
+            lines.push("");
+        }
+        if (def.helpExtra) {
+            const extra = typeof def.helpExtra === "function" ? def.helpExtra() : def.helpExtra;
+            lines.push(extra);
+            lines.push("");
+        }
+        return lines.join("\n");
+    }
+    /**
+     * Generates help text for an entire service, listing all its subcommands.
+     *
+     * @param service - Service name.
+     * @returns A formatted plain-text help string, or an error line if unknown.
+     */
+    function generateServiceHelp(service) {
+        const entry = options.getServiceEntry(service);
+        if (!entry)
+            return `  Unknown service: ${service}\n`;
+        const defs = options.getServiceDefinitions(service);
+        if (entry.isSingleCommand && defs?.length === 1) {
+            return generateCommandHelp(defs[0]);
+        }
+        const lines = [];
+        lines.push("");
+        lines.push(`  ${entry.label}`);
+        lines.push("");
+        lines.push("  USAGE");
+        lines.push(`    ${options.cliBinName} ${service} <command>${options.serviceUsageSuffix ?? " [flags]"}`);
+        lines.push("");
+        lines.push("  COMMANDS");
+        for (const c of entry.commands) {
+            lines.push("");
+            const riskTag = c.tag ? `  ${c.tag.trim()}` : "";
+            lines.push(`    ${c.command}${riskTag}`);
+            lines.push(`      ${c.description}`);
+            const def = defs?.find((d) => d.command === c.command);
+            if (def?.args && def.args.length > 0) {
+                lines.push("      ARGS");
+                const maxArgName = Math.max(...def.args.map((a) => a.name.length + 2));
+                for (const a of def.args) {
+                    const label = `<${a.name}>`.padEnd(maxArgName + 2);
+                    const req = a.required !== false ? " (required)" : "";
+                    lines.push(`        ${label}${a.description}${req}`);
+                }
+            }
+            const flags = def ? options.buildAllFlags(def).filter((f) => !f.hidden) : [];
+            if (flags.length > 0) {
+                const maxName = Math.max(...flags.map((f) => formatFlagName(f).length));
+                for (const fl of flags) {
+                    lines.push(`      ${formatFlagName(fl).padEnd(maxName + 2)}${renderFlagDesc(fl)}`);
+                }
+            }
+        }
+        lines.push("");
+        return lines.join("\n");
+    }
+    /**
+     * Generates the top-level `--help` output showing global options and
+     * all services with their command summaries.
+     *
+     * @returns A formatted plain-text help string.
+     */
+    function generateFullHelp() {
+        const lines = [];
+        lines.push("");
+        lines.push(`  ${options.cliDisplayName}`);
+        lines.push("");
+        lines.push("  USAGE");
+        lines.push(`    $ ${options.cliBinName} [global-options] <service> <command> [flags]`);
+        lines.push("");
+        lines.push("  GLOBAL OPTIONS");
+        const visibleFlags = options.globalFlags.filter((f) => !f.hidden);
+        const maxFlagLen = Math.max(...visibleFlags.map((f) => {
+            const hint = f.hint ? ` ${f.hint}` : "";
+            return `--${f.name}${hint}`.length;
+        }));
+        for (const f of visibleFlags) {
+            const hint = f.hint ? ` ${f.hint}` : "";
+            const label = `--${f.name}${hint}`.padEnd(maxFlagLen + 2);
+            lines.push(`    ${label}${f.description}`);
+        }
+        lines.push("");
+        lines.push("  COMMANDS");
+        lines.push("");
+        for (const entry of options.serviceRegistry) {
+            lines.push(`  ${entry.label}`);
+            if (entry.isSingleCommand) {
+                const cmd = entry.commands[0];
+                lines.push(`    ${entry.service.padEnd(18)}${cmd.description}${cmd.tag ?? ""}`);
+            }
+            else {
+                const fullNames = entry.commands.map((c) => `${entry.service} ${c.command}`);
+                const maxName = Math.max(...fullNames.map((n) => n.length));
+                for (let i = 0; i < entry.commands.length; i++) {
+                    const cmd = entry.commands[i];
+                    lines.push(`    ${fullNames[i].padEnd(maxName + 2)}${cmd.description}${cmd.tag ?? ""}`);
+                }
+            }
+            if (options.includeWildcardExtraInFullHelp && entry.wildcardDef?.helpExtra) {
+                const extra = typeof entry.wildcardDef.helpExtra === "function"
+                    ? entry.wildcardDef.helpExtra()
+                    : entry.wildcardDef.helpExtra;
+                for (const line of extra.split("\n")) {
+                    lines.push(`  ${line}`);
+                }
+            }
+            lines.push("");
+        }
+        lines.push(`  Run \`${options.cliBinName} <service> --help\` for service commands.`);
+        lines.push(`  Run \`${options.cliBinName} <service> <command> --help\` for command flags.`);
+        lines.push("");
+        return lines.join("\n");
+    }
+    return { generateCommandHelp, generateServiceHelp, generateFullHelp };
+}
+/**
+ * Formats a flag definition into its CLI representation.
+ *
+ * Examples:
+ * - `--dry-run`
+ * - `-f, --format <value>`
+ * - `-e, --env <env>`
+ *
+ * @param fl - Flag definition.
+ * @returns Formatted flag string with type hint and optional alias.
+ */
+function formatFlagName(fl) {
+    const typeSuffix = fl.type === "boolean" ? "" : fl.type === "number" ? " <n>" : " <value>";
+    const name = `--${fl.name}${typeSuffix}`;
+    if (!fl.alias)
+        return name;
+    return `-${fl.alias}, ${name}`;
+}
+/**
+ * Builds the description line for a flag, appending enum values, the
+ * default, and the `(required)` tag as applicable.
+ *
+ * @param fl - Flag definition.
+ * @returns Full description string with metadata annotations.
+ */
+function renderFlagDesc(fl) {
+    let desc = fl.description;
+    if (fl.enum && fl.enum.length > 0) {
+        desc += ` (${fl.enum.join(" | ")})`;
+    }
+    if (fl.default !== undefined && fl.default !== "" && fl.default !== false) {
+        desc += ` [default: ${fl.default}]`;
+    }
+    if (fl.required && !desc.includes("(required)")) {
+        desc += " (required)";
+    }
+    return desc;
+}

package/lib/framework/output.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @fileoverview Output formatting pipeline.
+ *
+ * Renders a {@link CommandResult} to stdout in one of three modes:
+ * - `json`    — Full indented JSON envelope.
+ * - `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).
+ */
+import type { CommandResult, OutputFormat, Risk } from "./types.js";
+/** Shared options passed through every internal print function. */
+interface OutputOptions {
+    /** Full command label (e.g. `"api list"`). */
+    command: string;
+    /** Risk level for the envelope. */
+    risk: Risk;
+    /** Resolved output format. */
+    format: OutputFormat;
+    /** `true` when this is a dry-run result. */
+    dryRun?: boolean;
+    /** Optional jq expression for post-filtering (json/compress modes only). */
+    jqFilter?: string;
+}
+/**
+ * Central formatting entry point used by the runner adapter.
+ *
+ * Dispatches to the appropriate internal printer based on `options.format`:
+ * - `"json"`     → {@link printJson}
+ * - `"compress"` → {@link printCompress}
+ * - `"pretty"`   → {@link printPretty}
+ *
+ * All output is written to stdout. Errors are written to stderr.
+ *
+ * @param result  - The command result to render.
+ * @param options - Formatting options including format, command label, risk, and jq filter.
+ *
+ * @example
+ * ```ts
+ * 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 {};